home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-19 / iritsm3s.zip / IRIT.SRC (.txt) < prev    next >
LaTeX Document  |  1992-03-10  |  134KB  |  3,019 lines
  1. ;This is the source file to create documentation for the IRIT solid modeler.
  2. ;First character in line specifies the action to take for this line/next block
  3. ;as follows:
  4. ; ';' - a comment that is always ignored.
  5. ; '#' - all lines following this line until next '#' are indented as an array.
  6. ;       Four integers follows specifying indentations, # of elements per
  7. ;       line, whether or not to put an internal vertical seperators, and
  8. ;       if entries are row ordered (1) or col ordered (2).
  9. ; '@' - latex only manual. Latex commands can appear within this line.
  10. ; '!' - plain text and irit docs only manual - keywords/headers.
  11. ; '&' - plain text only manual - headers.
  12. ; '$' - terminator for current block.
  13. ; latex commands can appear in regular text limited to a single line as
  14. ; {\command *}. For plain text the {\command } will be filtered out.
  15. ; Escaped characters via '\' (i.e. \#) will be left escaped (\#) in the
  16. ; latex output but unescaped (#) in the plain output.
  17. ;                       IRIT solid modeler (C) Gershon Elber 1991.
  18. @% Irit Solid modeler latex manual.
  19. @% Authors:     Gershon Elber
  20. @% Date:        Tri Nov 29, 1991
  21. @% Copyright (c) 1991 Gershon Elber
  22. @\documentstyle[11pt]{article}
  23. @\oddsidemargin  -.195in
  24. @\evensidemargin -.195in
  25. @\textwidth 6.50in
  26. @\topmargin -.5in
  27. @\textheight 9.5in
  28. @\begin{document}
  29. @\pagestyle{empty}
  30. @   \rule{0in}{3in}
  31. @   \begin{center}
  32. @       {\huge\bf IRIT}\\
  33. @       \vspace{3cm}
  34. @       {\Large A Solid modeling Program}\\
  35. @       \vspace{2cm}
  36. @       {\large Copyright (C) 1989, 1990, 1991 Gershon Elber}\\
  37. @       \vspace{1cm}
  38. @       {\large EMail: gershon@gr.utah.edu }\\
  39. @       \vfill
  40. @       {\small This manual is for IRIT version 3.0.}
  41. @   \end{center}
  42. @\newpage
  43. @\tableofcontents
  44. @\newpage
  45. @\setcounter{page}{1}
  46. @\markright{{\em {\bf Irit Solid modeler}}\hfil G. Elber}
  47. @\pagestyle{myheadings}
  48. @\newpage
  49. @%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  50. @\section{Introduction}
  51. !INTRODUCTION
  52.    {\em IRIT} is a small solid modeler developed for educational purposes. Although
  53.  small, it is now powerful enough to create quite complex scenes. I wrote
  54.  it mainly so I can learn all the little small and not so small problems
  55.  in developing such a system.
  56.    {\em IRIT} started as a polygonal solid modeler and was originally developed
  57.  (and mostly still is) on an IBM PC under MSDOS. Version 2.0 was also ported
  58.  to X11 and version 3.0 to SGI 4D systems. Version 3.0 also includes
  59.  quite a few free form curves and surfaces tools. See the UPDATE.NEW
  60.  file for more detailed update information.
  61. @\section{Copyrights}
  62. !COPYRIGHTS
  63.    BECAUSE {\em IRIT} AND ITS SUPPORTING TOOLS AS DOCUMENTED IN THIS DOCUMENT
  64.  ARE LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT
  65.  PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING, I
  66.  GERSHON ELBER PROVIDE {\em IRIT} PROGRAM AND ITS SUPPORTING TOOLS "AS IS" WITHOUT
  67.  WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED
  68.  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  69.  PURPOSE.
  70.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THESE PROGRAMS IS WITH
  71.  YOU. SHOULD THE {\em IRIT} PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
  72.  NECESSARY SERVICING, REPAIR OR CORRECTION.
  73.    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL GERSHON ELBER,
  74.  BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES,
  75.  OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
  76.  USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR A
  77.  FAILURE OF THE PROGRAMS TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY GERSHON
  78.  ELBER) THE PROGRAMS, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF
  79.  SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.
  80. @\smallskip
  81.    {\em IRIT} is a freeware solid modeler. It is not public domain since I
  82.  hold copyrights on it. However unless you are to sell or attempt to make
  83.  money from any part of this code and/or any model you made with this solid
  84.  modeler, you are free to make anything you want with it.
  85.    You are not obligated to me or to anyone else in any way by using {\em IRIT}.
  86.    You are encourage to share any model you made with it, but the models
  87.  you made with it are {\em yours}, and you have no obligation to share them.
  88.    You can use this program and/or any model created with it for any non
  89.  commerical and non profit purposes only. An acknowledgement on the way the
  90.  models were created would be nice but is {\em not} required.
  91. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  92. @\section{Command Line Options and Set Up}
  93. !SETUP
  94.    The {\em IRIT} program reads a file called {\bf IRIT.CFG} each time it is executed.
  95.    This file configures the system. It is a regular text file with comments, so
  96.  you can edit it and properly modify it for your environment.
  97.    This file is being searched for in all directories as specified by the
  98.  PATH environment variable on MSDOS BC++ port or in the IRIT\_PATH environment
  99.  variable under UNIX hosts or MSDOS DJGPP port.
  100.    For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
  101.    Note IRIT\_PATH must terminate with '/'. If the variables is not set only
  102.  the current directory is being searched for {\bf IRIT.CFG} under UNIX systems.
  103.    Since there exists a configuration file for MSDOS BC++ called IRIT-DOS.CFG,
  104.  for MSDOS DJGPP called IRIT\_DJG.CFG, and for UNIX called IRIT-UNX.CFG, make
  105.  sure you copy the right one for your system, into {\bf IRIT.CFG}.
  106.    In addition, if exists, a file by the name of {\bf IRITINIT.IRT} will be
  107.  automatically executed before any other '.irt' file. This file may contain
  108.  any {\em IRIT} command. It is the proper place to put your ALIASs if you have
  109.  some. This file will be searched much the same way {\bf IRIT.CFG} is. The
  110.  name of this initialization file may be changed by setting the StartFile
  111.  entry in the configuration file.
  112.    Under MSDOS the solid modeler can be executed in text mode (see the .cfg
  113.  and the -t flag below) on virtually any MSDOS compatible system. The BC++ port
  114.  uses Borlands BGI interface which makes it possible to use almost any device
  115.  that has a BGI interface from Hercules to a Super VGA. See the configuration
  116.  file for the supported device. The DJGPP port can be used on any system that
  117.  has graphic driver for it in this compiler.
  118.  Under BC++ the coprocessor will be used if detected but floating pointing
  119.  emulation will take place otherwise. Under DJGPP the provided emulator
  120.  (emu387) must be used if no 387 exists. If a mouse or a joystick exists
  121.  they can be use by enabling their respective flags in the configuration
  122.  file. The mouse sensitivity can be controlled via the configuration file
  123.  MouseSensitivity flag. In addition whether a mouse or a joystick exists or
  124.  not, the numeric keypad can be used to move the cursor as well. Shifted keys
  125.  will move the cursors 10 pixels at a time instead of one.
  126.    Since MSDOS does not support windowing system, an interface library called
  127.  intr\_lib is used and which provides the windowing and interfacing
  128.  capabilities expected from a windowing system. Four windows are created
  129.  under BC++, three under DJGPP:
  130. # 19 2 0 1
  131.  View
  132.   The window where geometry is displayed.
  133.  Transformation
  134.   The window holding the transformation interaction.
  135.   This window pops up with INTERACT command, by default.
  136.  Input
  137.   The window input is keyed in/sourced from a file.
  138.  Status
  139.   Status window, mainly for core left display (only BC++).
  140.    These windows can be placed everywhere in the screen by specifing their
  141.  position and size in the configuration file. Border width and color of
  142.  the window can be specified in the configuration file as well as other
  143.  window attributes such as smooth scrolling and window headers.
  144.    Furthermore, these windows can be moved, resized, poped, or pushed during
  145.  a session via a pop up window triggered by the left mouse button (EXECUTE -
  146.  see INTERACT) or F1 keystroke. Note however that while the mouse cursor is
  147.  on the Input window scroll bar or in the Trans window, EXECUTE has a
  148.  different meaning and the pop up menu will not be displayed. The following
  149.  entries can be found in the pop up menu, and their meaning.
  150. # 12 2 0 1
  151.  Redraw all
  152.   Redraw all windows. No window configuration is modified.
  153.  Move
  154.   Move a window. Window to move is picked by left mouse button.
  155.  Resize
  156.   Resize a window. Window to resize is picked as above.
  157.   Pop up a window. Window to pop up is picked as above.
  158.  Push
  159.   Push up a window. Window to push down is picked as above.
  160.  Zoom
  161.   Zoom a window to full screen. Window is picked as above.
  162.   Zoom on a zoomed window restore the window original size.
  163.  Reset
  164.   Reset all windows to their default position and size.
  165.  Headers
  166.   Toggle the display of windows header - names.
  167.   Under UNIX using X11 add the following options to your .Xdefaults. Most
  168.  are self explanatory. The Trans attributes control the transformation
  169.  window, while View control the view window. SubWin attributes control
  170.  the subwindows within the Transformation window.
  171. # 33 2 0 1
  172.  irit*Trans*BackGround:
  173.   NavyBlue
  174.  irit*Trans*BorderColor:
  175.   Red
  176.  irit*Trans*BorderWidth:
  177.  irit*Trans*TextColor:
  178.   Yellow
  179.  irit*Trans*SubWin*BackGround:
  180.   DarkGreen
  181.  irit*Trans*SubWin*BorderColor:
  182.   Magenta
  183.  irit*Trans*Geometry:
  184.   =150x500+500+0
  185.  irit*Trans*CursorColor:
  186.   Green
  187.  irit*View*BackGround:
  188.   NavyBlue
  189.  irit*View*BorderColor:
  190.   Red
  191.  irit*View*BorderWidth:
  192.  irit*View*Geometry:
  193.   =500x500+0+0
  194.  irit*View*CursorColor:
  195.   Red
  196.    If poly3d is used under SGI gl library, you can set the prefered windows
  197.  location in the poly3d.cfg. No color control is provided at this time.
  198.    A session can be logged into a file as set via LogFile in the configuration
  199.  file. See also the LOGFILE command.
  200.    When developing new model under MSDOS, it is extremely convenient to switch
  201.  between the solid modeler and an editor of your choice to edit the '.irt' file.
  202.  The solid modeler provides a way to fork to an editor of your choice to edit
  203.  the current '.irt' program you develop. Set EditPrgm (in irit.cfg) to the
  204.  editor of your choice, which should be small for fast access. Specify the
  205.  full path to that editor. Use the edit command in {\em IRIT} to call it. Only one
  206.  argument is given to the editor once forking to it - the '.irt' file name as
  207.  given to the edit command (see EDIT command). You can alias the command to
  208.  make it even faster as it is done in the current iritinit.irt - {\em IRIT}
  209.  initialization file.
  210.    Under UNIX one can use the gnu emacs irit.el {\em IRIT} mode provided in this
  211.  package to run {\em IRIT}.
  212.    The following command line options are available:
  213. @\begin{verbatim}
  214.    IRIT [-t] [-z] [file.irt]
  215. @\end{verbatim}
  216. # 10 2 1 1
  217.    Puts {\em IRIT} into text mode. No graphics will be displayed and
  218.    the INTERACT and VIEW commands will be ignored. Useful when
  219.    one needs to execute an irt file to create data on a tty device...
  220.    Prints usage message and current configuration/version
  221.    information.
  222.  file.irt
  223.    A file to directly invoke instead of waiting to input from
  224.    stdin.
  225. @\section{First Usage}
  226. !FIRSTUSAGE
  227.    Once executed, the program opens four windows under MSDOS BC++ (three
  228.  under MSDOS DJGPP - no status window): view, status, trans and input windows,
  229.  and opens a view window under UNIX.
  230.    Commands are entered through the input window, which is in the same window
  231.  as the shell executed {\em IRIT} under UNIX. Objects are viewed in the view
  232.  window, and the status window is used as an auxiliary window (MSDOS only).
  233.    Some important commands to begin with are
  234.    1. include("file.irt"); - will execute the commands in file.irt. Note
  235.       include can be recursive up to 10 levels. To execute the demo
  236.       (demo.irt) simply type 'include("demo.irt");'. Another way to run
  237.       the demo is by typing DEMO (must be capitalized as this is an alias
  238.       loaded via the iritinit.irt initialization file - see the ALIAS
  239.       command for more).
  240.    2. help(""); - will print all available commands and how to get help on
  241.       them. A file by the name irit.hlp will be searched as irit.cfg is
  242.       being searched (see above), to provide the help.
  243.    3. exit(); - close everything and exit {\em IRIT}.
  244.    Be careful. Most operators are overloaded. This means that you can multiply
  245.  two scalars (numbers) or two vectors or even two matrices with the same
  246.  multiplication symbol ($*$). To get its on line type 'help("$*$");'
  247.    The best way to learn this program (like any other program...) is by
  248.  playing with it. Print the manual and study each of the commands available.
  249.    Study the demo programs ($*$.irt) provided as well.
  250.    Under MSDOS, input from keyboard has full line editing capability:
  251.    1. Up/Down arrow : retrieve old command for 10 last commands.
  252.    2. Left/Right arrows : to move left and right along the line.
  253.    3. Home/End : to move to beginning/end of line.
  254.    4. Delete : to delete the character the cursor is on.
  255.    5. Back space : to delete one char backward.
  256.    6. Insert : toggles insert/overwrite mode. Note cursor shape is modified.
  257.    7. Esc : clear the entire line.
  258.    8. CR : to accept line and quit.
  259. @\section{Data Types}
  260. !DATATYPES
  261.   These are the Data Types recognized the system. They are also used to
  262.  define the calling sequences of the different functions below:
  263. # 18 2 1 1
  264.  {\bf ConstantType}
  265.   Scalar real type that cannot be modified.
  266.  {\bf NumericType}
  267.   Scalar real type.
  268.  {\bf VectorType}
  269.   3D real type vector (points/vectors).
  270.  {\bf CtlPtType}
  271.   Curve or Surface Control Point.
  272.  {\bf MatrixType}
  273.   4 by 4 matrix (homogeneous transformation matrix).
  274.  {\bf PolygonType}
  275.   Object consists of Polygons.
  276.  {\bf PolylineType}
  277.   Object consists of Polylines.
  278.  {\bf CurveType}
  279.   Object consists of Curves.
  280.  {\bf SurfaceType}
  281.   Object consists of Surfaces.
  282.  {\bf GeometriceType}
  283.   One of Polygon/lineType, CurveType, SurfaceType.
  284.  {\bf GeometricTreeType}
  285.   A list of GeometricTypes or GeometricTreeTypes.
  286.  {\bf StringType}
  287.   Sequence of chars within double quotes - "A string".
  288.   Current implementation is limited to 80 chars.
  289.  {\bf AnyType}
  290.   Any of the above.
  291.  {\bf ListType}
  292.   List of (any of the above type) objects. Implementation 
  293.   is currently limited to 250 (50 MSDOS) objects in a list.
  294. @\section{Commands summary}
  295. !COMMANDS
  296.  These are all the commands and operators supported by the {\em IRIT} solid modeler:
  297. # 11 6 1 0
  298.  \verb+^+
  299.  ACOS
  300.  ALIAS
  301.  AREA
  302.  ASIN
  303.  ATAN
  304.  ATAN2
  305.  ATTRIB
  306.  BEEP
  307.  BOOLSUM
  308.  CBEZIER
  309.  CBSPLINE
  310.  CDIVIDE
  311.  CEDITPT
  312.  CEVAL
  313.  CHDIR
  314.  CIRCLE
  315.  CIRCPOLY
  316.  CLOSED
  317.  CMESH
  318.  COLOR
  319.  COMMENT
  320.  CON2
  321.  CONE
  322.  CONVEX
  323.  CPOLY
  324.  CRAISE
  325.  CREFINE
  326.  CREGION
  327.  CROSSEC
  328.  CSURFACE
  329.  CTANGENT
  330.  CTLPT
  331.  CYLIN
  332.  EDIT
  333.  EXIT
  334.  EXTRUDE
  335.  FREE
  336.  GBOX
  337.  GPOLYGON
  338.  GPOLYLINE
  339.  HELP
  340.  INCLUDE
  341.  INTERACT
  342.  LIST
  343.  LOAD
  344.  LOGFILE
  345.  MERGEPOLY
  346.  NORMAL
  347.  OFFSET
  348.  PAUSE
  349.  POLY
  350.  ROTX
  351.  ROTY
  352.  ROTZ
  353.  RULEDSRF
  354.  SAVE
  355.  SBEZIER
  356.  SBSPLINE
  357.  SCALE
  358.  SDIVIDE
  359.  SEDITPT
  360.  SEVAL
  361.  SFROMCRVS
  362.  SNOC
  363.  SNORMAL
  364.  SPHERE
  365.  SQRT
  366.  SRAISE
  367.  SREFINE
  368.  SREGION
  369.  STANGENT
  370.  SURFREV
  371.  SWEEPSRF
  372.  SYSTEM
  373.  TIME
  374.  TORUS
  375.  TRANS
  376.  VARLIST
  377.  VECTOR
  378.  VIEW
  379.  VOLUME
  380. @\section{Functions and Variables}
  381. !FUNCTIONS
  382. @ This sections lists all the functions supported by the {\em IRIT} system
  383. @ according to their classes - the object type they return.
  384.  These are the functions returning a {\bf NumericType}:
  385. # 11 5 1 0
  386.  ACOS
  387.  AREA
  388.  ASIN
  389.  ATAN
  390.  ATAN2
  391.  CPOLY
  392.  SQRT
  393.  VOLUME
  394.  These are the functions returning a {\bf GeometricType}:
  395. # 11 6 1 0
  396.  BOOLSUM
  397.  CBEZIER
  398.  CBSPLINE
  399.  CDIVIDE
  400.  CEDITPT
  401.  CEVAL
  402.  CIRCLE
  403.  CIRCPOLY
  404.  CMESH
  405.  CON2
  406.  CONE
  407.  CONVEX
  408.  CPOLY
  409.  CRAISE
  410.  CREFINE
  411.  CREGION
  412.  CROSSEC
  413.  CSURFACE
  414.  CTANGENT
  415.  CTLPT
  416.  CYLIN
  417.  EXTRUDE
  418.  GBOX
  419.  GPOLYGON
  420.  GPOLYLINE
  421.  MERGEPOLY
  422.  OFFSET
  423.  POLY
  424.  RULEDSRF
  425.  SBEZIER
  426.  SBSPLINE
  427.  SDIVIDE
  428.  SEDITPT
  429.  SEVAL
  430.  SFROMCRVS
  431.  SNORMAL
  432.  SPHERE
  433.  SRAISE
  434.  SREFINE
  435.  SREGION
  436.  STANGENT
  437.  SURFREV
  438.  SWEEPSRF
  439.  TORUS
  440.  These are the functions to linearly transform an object:
  441. # 11 5 1 0
  442.  ROTX
  443.  ROTY
  444.  ROTZ
  445.  SCALE
  446.  TRANS
  447.  These are the miscellaneous functions:
  448. # 11 6 1 0
  449.  ALIAS
  450.  ATTRIB
  451.  BEEP
  452.  CHDIR
  453.  CLOSED
  454.  COLOR
  455.  COMMENT
  456.  EDIT
  457.  EXIT
  458.  FREE
  459.  HELP
  460.  INCLUDE
  461.  INTERACT
  462.  LIST
  463.  LOAD
  464.  LOGFILE
  465.  NORMAL
  466.  PAUSE 
  467.  SAVE
  468.  SNOC
  469.  SYSTEM
  470.  TIME
  471.  VARLIST
  472.  VECTOR
  473.  VIEW
  474.  These are the variables predefined in the system:
  475. # 11 5 1 0
  476.  AXES
  477.  DRAWCTLPT
  478.  DUMPLVL
  479.  ECHOSRC
  480.  FLAT4PLY
  481.  INTERCRV
  482.  INTERNAL
  483.  MACHINE
  484.  RESOLUTION
  485.  VIEW\_MAT
  486.  These are the constants predefined in the system:
  487. # 11 6 1 0
  488.  APOLLO
  489.  BLACK
  490.  BLUE
  491.  CYAN
  492.  FALSE
  493.  GREEN
  494.  KV\_FLOAT
  495.  KV\_OPEN
  496.  MAGENTA
  497.  MSDOS
  498.  TRUE
  499.  UNIX  
  500.  WHITE
  501.  YELLOW
  502. @\section{Language description}
  503. !LANGUAGE
  504.     The front end of the {\em IRIT} solid modeler is an infix parser that mimics
  505.  some of the C language behavior. The infix operators that are supported
  506.  are plus (+), minus (-), multiply (*), divide (/), and power (\verb+^+) for
  507.  numeric operators and with the same precedence as in C.
  508.     However, unlike the C language, these operators are overloaded,
  509. @\footnote{In fact the C language do support overloaded operators to some
  510. @extent: '1 + 2' and '1.0 + 2.0' implies invocation of two different
  511. @actions.}
  512.  or different action is taken based upon the different operands.
  513.    This means that one can write '1 + 2' in which the plus sign is a regular
  514.  numetic addition, or one can write 'PolyObj1 + PolyObj2' in which the plus
  515.  sign is now the Boolean operation of union between two geometric objects.
  516.    The exact way each operator is overloaded is defined below.
  517.    In this environment the representation of reals, integers, and even
  518.  Boolean data is identical. Data is automatically promoted as necessary.
  519.  The constants TRUE and FALSE are defined as 1.0 and 0.0 respectively,
  520.  for example.
  521.    Each expression is terminated by a semicolon. An expression can be as
  522.  simple as 'a;' which prints the value of variable a, or as complex as:
  523. @\begin{verbatim}
  524.     for ( (t = 1.1), 0.1, 1.9,
  525.             (
  526.                ( cb1 = csurface( sb, COL, t ) ):
  527.                color( cb1, green ):
  528.                snoc( cb1, cb_all )
  529.             )
  530.         );
  531. @\end{verbatim}
  532.    Once a complete expression is read in and parsed correctly (i.e. no syntax
  533.  errors were found), it is executed. Before each operator or a function
  534.  are executed, parameter type matching tests are being made to make sure
  535.  the operator can be applied to these operand(s), or the function gets the
  536.  correct set of arguments.
  537.    The parser is almost totally case insensitive (with one exception - see
  538.  the ALIAS command) so Obj, obj and OBJ will refer to the same object while
  539.  MergePoly, MERGEPOLY, and margePoly will refer to the same function.
  540.    Objects (Variables if you prefer) need not be declared. Simply use them
  541.  when you need them. Object names may be any alpha-numeric (and underscore)
  542.  string of at most 10 characters. By assigning to an old object, the old
  543.  object will be automatically deleted and if necessary its type will be
  544.  changing on the fly. For example:
  545. @\begin{verbatim}
  546.     V = sin( 45 * pi / 180.0 );
  547.     V = V * vector( 1, 2, 3 );
  548.     V = V * rotx( 90 );
  549.     V = V * V;
  550. @\end{verbatim}
  551.  will assign to V a NumericType of sine of 45 degrees, the VectorType
  552.  ( 1, 2, 3 ) scaled by the sine of 45, rotate that vector around the X axis
  553.  by 90 degrees, and finally a NumericType which is its dot product.
  554.    The parser will read from stdin unless a file was specified on the command
  555.  line or an INCLUDE command was executed. In both cases, when done reading
  556.  from the file, the parser will again wait for input from stdin. In order
  557.  to execute a file and quit when the file is done, put an EXIT command as
  558.  the last command in the file.
  559. @\section{Operator overloading}
  560. @ This section lists the way the basic operators $+$, $-$, $*$, $/$, and
  561. @ \verb+^+ are overloaded. In other words, what action is taken by each
  562. @ of these operators depending upon its arguments.
  563. @\subsection{Overloading $+$}
  564.  The $+$ operator is overloaded above the following domains:
  565. @\begin{verbatim}
  566.   NumericType + NumericType -> NumericType
  567.   VectorType  + VectorType  -> VectorType
  568.   MatrixType  + MatrixType  -> MatrixType
  569.   PolygonType + PolygonType -> PolygonType  (Boolean UNION operation)
  570.   CurveType   + CurveType   -> CurveType    (Curve curve chaining)
  571.   CurveType   + CtlPtType   -> CurveType    (Curve control point chaining)
  572.   CtlPtType   + CtlPtType   -> CurveType    (Control points chaining)
  573.   ListType    + ListType    -> ListType     (Append lists operator)
  574. @\end{verbatim}
  575.  Note: Boolean UNION of two disjoint objects (no common volume) will result
  576.  with the two objects combined. It is the USER responsibility to make sure that
  577.  the non intersecting object are also disjoint - this system only tests for
  578.  no intersection.
  579. @\subsection{Overloading $-$}
  580.  The $-$ operator is overloaded above the following domains:
  581.  As a Diadic operator:
  582. @\begin{verbatim}
  583.   NumericType - NumericType -> NumericType
  584.   VectorType  - VectorType  -> VectorType
  585.   MatrixType  - MatrixType  -> MatrixType
  586.   PolygonType - PolygonType -> PolygonType (Boolean SUBTRACT operation)
  587. @\end{verbatim}
  588.  As a Monadic operator:
  589. @\begin{verbatim}
  590.   - NumericType -> NumericType
  591.   - VectorType  -> VectorType    (Scaling all vector by -1)
  592.   - MatrixType  -> MatrixType    (Scaling all matrix by -1)
  593.   - PolygonType -> PolygonType   (Boolean NEGATION operation)
  594.   - CurveType   -> CurveType     (Curve parameterization is reversed)
  595.   - SurfaceType -> SurfaceType   (Surface parameterization is reversed)
  596. @\end{verbatim}
  597.  Note: Boolean SUBTRACT of two disjoint objects (no common volume) will result
  598.  with an empty object. For both a curve and a surface parameterization reverse
  599.  opeartion (Monadic minus) causes the object normal to be flipped as a side
  600.  effect.
  601. @\subsection{Overloading $*$}
  602.  The $*$ operator is overloaded above the following domains:
  603. @\begin{verbatim}
  604.   NumericType * NumericType   -> NumericType
  605.   VectorType  * NumericType   -> VectorType     (Vector scaling)
  606.   VectorType  * VectorType    -> NumericType    (Inner product)
  607.   MatrixType  * NumericType   -> MatrixType     (Matrix Scaling)
  608.   MatrixType  * VectorType    -> VectorType     (Vector transform)
  609.   MatrixType  * MatrixType    -> MatrixType     (Matrix multiplication)
  610.   MatrixType  * GeometricType -> GeometricType  (Object transform)
  611.   MatrixType  * ListType      -> ListType       (Object hierarchy transform)
  612.   PolygonType * PolygonType   -> PolygonType    (Boolean INTERSECTION operation)
  613. @\end{verbatim}
  614.  Note: Boolean INTERSECTION of two disjoint objects (no common volume) will
  615.  result with an empty object. Object hierarchy transform transforms any
  616.  transformable object (GeometricType) found in the list recursively.
  617. @\subsection{Overloading $/$}
  618.  The $/$ operator is overloaded above the following domains:
  619. @\begin{verbatim}
  620.   NumericType / NumericType -> NumericType
  621.   PolygonType / PolygonType -> PolygonType   (Boolean CUT operation)
  622. @\end{verbatim}
  623.  Note: Boolean CUT of two disjoint objects (no common volume) will result
  624.  with an empty object.
  625. @\subsection{Overloading \^{\ }}
  626.  The \verb+^+ operator is overloaded above the following domains:
  627. @\begin{verbatim}
  628.   NumericType ^ NumericType -> NumericType
  629.   MatrixType  ^ NumericType -> MatrixType   (Matrix to the power)
  630.   PolygonType ^ PolygonType -> PolygonType  (Boolean MERGE operation)
  631. @\end{verbatim}
  632.  Note: Boolean MERGE simply merges the two sets of polygons without any
  633.  intersection tests. Matrix powers must be positive integers or -1 in which
  634.  the matrix inverse (if exists) is computed.
  635. @\subsection{Assignments}
  636.    Assignments are allowed as side effects, any place in any expressions:
  637.  If Expr is an expression, then (var = Expr) is the exact same expression
  638.  with the side effect of setting Var to that value. There is no guarantee
  639.  on the order of evaluation, so using Vars that are set within same
  640.  expression are a bad practice.
  641.    Any assignment which is not at top level, MUST be within parenthesis.
  642. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  643. @\section{Function's Description}
  644. &Function's Description
  645. @ The function description below defines their calling sequence in ANSI C
  646. @ notation. Listed are all the functions the system knows about in alphabetic
  647. @ order, according to their classes.
  648. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  649. @\subsection{NumericType returning functions}
  650. &NumericType returning functions
  651. @\subsubsection{ABS}
  652. @\begin{verbatim}
  653.  NumericType ABS( NumericType Operand )
  654. @\end{verbatim}
  655.    Returns the absolute value of the given {\bf Operand}.
  656. @\subsubsection{ACOS}
  657. !ACOS
  658. @\begin{verbatim}
  659.  NumericType ACOS( NumericType Operand )
  660. @\end{verbatim}
  661.    Returns the arc cosine value (in radians) of the given {\bf Operand}.
  662. @\subsubsection{AREA}
  663. !AREA
  664. @\begin{verbatim}
  665.  NumericType AREA( PolygonType Object )
  666. @\end{verbatim}
  667.    Return the area of the given {\bf Object} (in object units). Returned is
  668.  the real area of the polygonal object - not the primitive it might approximate.
  669.    That means that the area of a polygonal approximation to a sphere will be
  670.  returned, not the sphere area.
  671. @\subsubsection{ASIN}
  672. !ASIN
  673. @\begin{verbatim}
  674.  NumericType ASIN( NumericType Operand )
  675. @\end{verbatim}
  676.    Returns the arc sine value (in radians) of the given {\bf Operand}.
  677. @\subsubsection{ATAN}
  678. !ATAN
  679. @\begin{verbatim}
  680.  NumericType ATAN( NumericType Operand )
  681. @\end{verbatim}
  682.    Returns the arc tangent value (in radians) of the given {\bf Operand}.
  683. @\subsubsection{ATAN2}
  684. !ATAN2
  685. @\begin{verbatim}
  686.  NumericType ATAN2( NumericType Operand1, NumericType Operand2 )
  687. @\end{verbatim}
  688.    Returns the arc tangent value (in radians) of the given ratio:
  689.  {\bf Operand1} / {\bf Operand2}, over the whole angle circle.
  690. @\subsubsection{COS}
  691. @\begin{verbatim}
  692.  NumericType COS( NumericType Operand )
  693. @\end{verbatim}
  694.    Returns the cosine value of the given {\bf Operand} (in radians).
  695. @\subsubsection{CPOLY}
  696. !CPOLY
  697. @\begin{verbatim}
  698.  NumericType CPOLY( PolygonType Object )
  699. @\end{verbatim}
  700.    Returns the number of polygons in the given polygonal {\bf Object}.
  701. @\subsubsection{EXP}
  702. @\begin{verbatim}
  703.  NumericType EXP( NumericType Operand )
  704. @\end{verbatim}
  705.    Returns the natural exponent value of the given {\bf Operand}.
  706. @\subsubsection{LN}
  707. @\begin{verbatim}
  708.  NumericType LN( NumericType Operand )
  709. @\end{verbatim}
  710.    Returns the natural logarithm value of the given {\bf Operand}.
  711. @\subsubsection{LOG}
  712. @\begin{verbatim}
  713.  NumericType LOG( NumericType Operand )
  714. @\end{verbatim}
  715.    Returns the base 10 logarithm value of the given {\bf Operand}.
  716. @\subsubsection{SIN}
  717. @\begin{verbatim}
  718.  NumericType SIN( NumericType Operand )
  719. @\end{verbatim}
  720.    Returns the sine value of the given {\bf Operand} (in radians).
  721. @\subsubsection{SQRT}
  722. !SQRT
  723. @\begin{verbatim}
  724.  NumericType SQRT( NumericType Operand )
  725. @\end{verbatim}
  726.    Returns the square root value of the given {\bf Operand}.
  727. @\subsubsection{TAN}
  728. @\begin{verbatim}
  729.  NumericType TAN( NumericType Operand )
  730. @\end{verbatim}
  731.    Returns the tangent value of the given {\bf Operand} (in radians).
  732. @\subsubsection{VOLUME}
  733. !VOLUME
  734. @\begin{verbatim}
  735.  NumericType VOLUME( PolygonType Object )
  736. @\end{verbatim}
  737.    Return the volume of the given {\bf Object} (in object units). Returned is
  738.  the real volume of the polygonal object - not the object it might approximate.
  739.    This routine decompose all non convex polygons to convex ones as side
  740.  effect (see CONVEX).
  741. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  742. @\subsection{GeometricType returning functions}
  743. &GeometricType returning functions
  744. @\subsubsection{ARC}
  745. @\begin{verbatim}
  746.  CurveType ARC( VectorType StartPos, VectorType Center, VectorType EndPos )
  747. @\end{verbatim}
  748.  An arc constructor between two end points {\bf StartPos} and {\bf EndPos}
  749.  centered at {\bf Center}. Arc will always be less than 180 degrees so the
  750.  shortest arc path from {\bf StartPos} to {\bf EndPos} is selected. The
  751.  case where {\bf StartPos}, {\bf Center}, and {\bf EndPos} are colinear is
  752.  illegal, since it attempts to define a 180 degrees arc. Arc is constructed
  753.  as a single rational quadratic Bezier curve. Example:
  754. @\begin{verbatim}
  755.     Arc1 = ARC( vector( 1.0, 0.0, 0.0 ),
  756.                 vector( 1.0, 1.0, 0.0 ),
  757.                 vector( 0.0, 1.0, 0.0 ) );
  758. @\end{verbatim}
  759.  constructs a 90 degrees arc tangent to both X and Y axes at coordinate 1.
  760. @\subsubsection{BOOLSUM}
  761. !BOOLSUM
  762. @\begin{verbatim}
  763.  SurfaceType BOOLSUM( CurveType Crv1, CurveType Crv2,
  764.                       CurveType Crv3, CurveType Crv4 )
  765. @\end{verbatim}
  766.  Construct a surface using the provided four curves as its four boundary
  767.  curves. Curves do not have to have the same order or type and will be
  768.  promoted to their least common denominator. The four curves end points
  769.  should match as follows:
  770. # 30 2 0 1
  771.  {\bf Crv1} start point,
  772.   to {\bf Crv3} start point.
  773.  {\bf Crv1} end point,
  774.   to {\bf Crv4} start point.
  775.  {\bf Crv2} start point,
  776.   to {\bf Crv3} end point.
  777.  {\bf Crv2} end point,
  778.   to {\bf Crv4} end point.
  779.  where {\bf Crv1} and {\bf Crv2} are the two boundaries in one parameteric
  780.  direction and {\bf Crv3} and {\bf Crv4} are the two in the other.
  781.  Example:
  782. @\begin{verbatim}
  783.     Cbzr1 = cbezier( list( ctlpt( E3, 0.1, 0.1, 0.1 ),
  784.                            ctlpt( E3, 0.0, 0.5, 1.0 ),
  785.                            ctlpt( E3, 0.4, 1.0, 0.4 ) ) );
  786.     Cbzr2 = cbezier( list( ctlpt( E3, 1.0, 0.2, 0.2 ),
  787.                            ctlpt( E3, 1.0, 0.5, -1.0 ),
  788.                            ctlpt( E3, 1.0, 1.0, 0.3 ) ) );
  789.     Cbsp3 = cbspline( 4,
  790.                       list( ctlpt( E3, 0.1,  0.1, 0.1 ),
  791.                             ctlpt( E3, 0.25, 0.0, -1.0 ),
  792.                             ctlpt( E3, 0.5,  0.0, 2.0 ),
  793.                             ctlpt( E3, 0.75, 0.0, -1.0 ),
  794.                             ctlpt( E3, 1.0,  0.2, 0.2 ) ),
  795.                       list( KV_OPEN ) );
  796.     Cbsp4 = cbspline( 4,
  797.                       list( ctlpt( E3, 0.4,  1.0, 0.4 ),
  798.                             ctlpt( E3, 0.25, 1.0, 1.0 ),
  799.                             ctlpt( E3, 0.5,  1.0, -2.0 ),
  800.                             ctlpt( E3, 0.75, 1.0, 1.0 ),
  801.                             ctlpt( E3, 1.0,  1.0, 0.3 ) ),
  802.                       list( KV_OPEN ) );
  803.     Srf = BOOLSUM( Cbzr1, Cbzr2, Cbsp3, Cbsp4 );
  804. @\end{verbatim}
  805. @\subsubsection{BOX}
  806. @\begin{verbatim}
  807.  PolygonType BOX( VectorType Point,
  808.                   NumericType Dx, NumericType Dy, NumericType Dz )
  809. @\end{verbatim}
  810.    Creates a main planes parallel BOX polygonal object, defined by {\bf Point} as
  811.  base position, and {\bf Dx, Dy, Dz} as BOX dimensions. Note negative dimensions
  812.  are allowed. Example:
  813. @\begin{verbatim}
  814.     B = BOX( vector( 0, 0, 0 ), 1, 1, 1);
  815. @\end{verbatim}
  816.  creates a unit cube from 0 to 1 in all axes.
  817. @\subsubsection{CBEZIER}
  818. !CBEZIER
  819. @\begin{verbatim}
  820.  CurveType CBEZIER( ListType CtlPtList )
  821. @\end{verbatim}
  822.    Creates a Bezier curve out of the provided control point list. {\bf CtlPtList}
  823.  is a list of control points, all of the same type (E2, E3, P2, or P3).
  824.  Example:
  825. @\begin{verbatim}
  826.     s45 = sin(pi / 4);
  827.     Arc90 = CBEZIER( list( ctlpt( P2, 1.0, 0.0, 1.0 ),
  828.                            ctlpt( P2, s45, s45, s45 ),
  829.                            ctlpt( P2, 1.0, 1.0, 0.0 ) ) );
  830. @\end{verbatim}
  831.  constructs an arc of 90 degrees as a rational quadratic Bezier curve.
  832. @\subsubsection{CBSPLINE}
  833. !CBSPLINE
  834. @\begin{verbatim}
  835.  CurveType CBSPLINE( NumericType Order, ListType CtlPtList,
  836.                                                         ListType KnotVector )
  837. @\end{verbatim}
  838.    Creates a Bspline curve out of the provided control point list and the
  839.  knot vector, with the specified order. {\bf CtlPtList} is a list of control points,
  840.  all of the same type (E2, E3, P2, or P3) defining the curve control polygon.
  841.  The length of the {\bf KnotVector} must be equal to the number of control
  842.  points in {\bf CtlPtList} plus {\bf Order}.
  843.  Example:
  844. @\begin{verbatim}
  845.     s45 = sin(pi / 4);
  846.     HalfCirc = CBSPLINE( 3,
  847.                       list( ctlpt( P3, 1.0,  0.0, 0.0,  1.0 ),
  848.                             ctlpt( P3, s45, -s45, 0.0,  s45 ),
  849.                             ctlpt( P3, 1.0, -1.0, 0.0,  0.0 ),
  850.                             ctlpt( P3, s45, -s45, 0.0, -s45 ),
  851.                             ctlpt( P3, 1.0,  0.0, 0.0, -1.0 ) ),
  852.                       list( 0, 0, 0, 1, 1, 2, 2, 2 ) );
  853. @\end{verbatim}
  854.  constructs an arc of 180 degrees in the XZ plane as a rational quadratic
  855.  Bspline curve.
  856.    The knot vector list may be specified as {\bf list( KV\_OPEN )} or as
  857.  {\bf list( KV\_FLOAT )} in which a uniform open or floating knot vector
  858.  with the appropriate length is automatically constructed. 
  859. @\subsubsection{CDIVIDE}
  860. !CDIVIDE
  861. @\begin{verbatim}
  862.  ListType CDIVIDE( CurveType Curve, NumericType Param )
  863. @\end{verbatim}
  864.    Subdivides a curve into two at the specified parameter value. {\bf Curve}
  865.  can be either a Bspline curve in which {\bf Param} must be within Curve
  866.  parametric domain or a Bezier curve in which {\bf Param} must be in the
  867.  0 to 1 range.
  868.    Returned is a list of the two sub-curves. The individual curves may be
  869.  extracted from the list using the NTH command. For example:
  870. @\begin{verbatim}
  871.  CrvLst = CDIVIDE( Crv, 0.5 );
  872.  Crv1 = nth( CrvLst, 1 );
  873.  Crv2 = nth( CrvLst, 2 );
  874. @\end{verbatim}
  875.  subdivides the curve {\bf Crv} at the parameter value 0.5.
  876. @\subsubsection{CEDITPT}
  877. !CEDITPT
  878. @\begin{verbatim}
  879.  CurveType CEDITPT( CurveType Curve, CtlPtType CtlPt, NumericType Index )
  880. @\end{verbatim}
  881.    Provides a simple mechanism to manually modify a single control point number
  882.  {\bf Index} (base count is 0) in {\bf Curve}, by substituting {\bf CtlPt}
  883.  instead. {\bf CtlPt} must have the same point type as {\bf Curve} points.
  884.  Original curve {\bf Curve} is not modified. Example:
  885. @\begin{verbatim}
  886.     CPt = ctlpt( E3, 1, 2, 3 );
  887.     NewCrv = CEDITPT( Curve, CPt, 1 );
  888. @\end{verbatim}
  889.  constructs a {\bf NewCrv} with the second control point of {\bf Curve} being
  890.  {\bf CPt}.
  891. @\subsubsection{CEVAL}
  892. !CEVAL
  893. @\begin{verbatim}
  894.  CtlPtType CEVAL( CurveType Curve, NumericType Param )
  895. @\end{verbatim}
  896.    Evaluates the provided {\bf Curve} at the given {\bf Param } value.
  897.  {\bf Param} should be with the curve domain if {\bf Curve} is a Bspline
  898.  curve, or between 0 and 1 if {\bf Curve} is a Bezier curve. Returned
  899.  control point has the same type as the {\bf Curve} control points. Example:
  900. @\begin{verbatim}
  901.     CPt = CEVAL( Crv, 0.25 );
  902. @\end{verbatim}
  903.  evaluates {\bf Crv} at the parameter value of 0.25.
  904. @\subsubsection{CIRCLE}
  905. !CIRCLE
  906. @\begin{verbatim}
  907.  CurveType CIRCLE( VectorType Center, NumericType Radius )
  908. @\end{verbatim}
  909.    Construct a circle at the specified {\bf Center} with the specified
  910.  {\bf Radius}. Returned circle is a Bspline curve of four piecewise Bezier
  911.  90 degree arcs. Circle is always parallel to the XY plane. Use the linear
  912.  transformation routines to place the circle in the appropriate location.
  913. @\subsubsection{CIRCPOLY}
  914. !CIRCPOLY
  915. @\begin{verbatim}
  916.  PolygonType CIRCPOLY( VectorType Normal, VectorType Trans, NumericType Radius )
  917. @\end{verbatim}
  918.    As in this solid modeler, open objects are allowed (although any two
  919.  objects intersection should form a closed loop), a plane (open!) object
  920.  also exists. The function defines a circular polygon with the given
  921.  {\bf Normal}, and includes the {\bf Trans} point. It is implemented as a FINITE
  922.  circle with resolution (see RESOLUTION) edges, radius {\bf Radius} and center
  923.  {\bf Trans} on that plane. It is the user responsibility to make sure that any
  924.  Boolean operation on it (or any other open object) will create closed loops as
  925.  intersecting curves and/or open loops terminated on its boundary (no
  926.  termination in the middle of it is allowed).
  927.    Alternative to the function are manual construction of the required plane 
  928.  as a single polygon using POLY, or construction of a flat ruled surface using
  929.  RULEDSRF.
  930. @\subsubsection{CMESH}
  931. !CMESH
  932. @\begin{verbatim}
  933.  CurveType CMESH( SurfaceType Srf, ConstantType Direction, NumericType Index )
  934. @\end{verbatim}
  935.    Returns a single ROW or COLumn as specified by the {\bf Direction} and
  936.  {\bf Index} (base count is 0) of the surface {\bf Srf} control mesh.
  937.    Returned curve will have the same knot vector as {\bf Srf} in the
  938.  appropriate direction. See also CSURFACE.
  939.    Note this curve is {\em not} necessarily in the surface {\bf Srf}. Example:
  940. @\begin{verbatim}
  941.     Crv = CMESH( Srf, COL, 0 );
  942. @\end{verbatim}
  943.  extracts the first column of surface {\bf Srf} as a curve.
  944. @\subsubsection{CON2}
  945. !CON2
  946. @\begin{verbatim}
  947.  PolygonType CON2( VectorType Center, VectorType Direction,
  948.                    NumericType Radius1, NumericType Radius2 )
  949. @\end{verbatim}
  950.    Create a truncated CONE geometric object, defined by {\bf Center} as CONE main
  951.  base center, CONE axes {\bf Direction}, and CONE base radii {\bf Radius1/2}.
  952.    Note {\bf Direction} magnitude also sets the CONE height. {\bf Direction} can be any
  953.  3D vector.
  954.    Unlike the regular cone (CONE) constructor which has discontinuities in
  955.  its apex generated normals, CON2 may be used to form a truncated cone but
  956.  with continuous normals. 
  957.    See RESOLUTION for accuracy of CON2 approximation as polygonal model. 
  958.    Example:
  959. @\begin{verbatim}
  960.     Crv = CON2( vector( 0, 0, -1 ), vector( 0, 0, 4 ), 2, 1 );
  961. @\end{verbatim}
  962.  constructs a truncated cone based at the XY parallel plane Z = -1, top at
  963.  plane Z = 3, and with radii of 2 and 1 respectively.
  964. @\subsubsection{CONE}
  965. !CONE
  966. @\begin{verbatim}
  967.  PolygonType CONE( VectorType Center, VectorType Direction,
  968.                    NumericType Radius )
  969. @\end{verbatim}
  970.    Create a CONE geometric object, defined by {\bf Center} as CONE base center,
  971.  CONE axes {\bf Direction}, and CONE base radius {\bf Radius}. Note {\bf Direction} magnitude
  972.  also sets the CONE height. {\bf Direction} can be any 3D vector.
  973.    See RESOLUTION for accuracy of CONE approximation as polygonal model. 
  974.    Example:
  975. @\begin{verbatim}
  976.     Crv = CONE( vector( 0, 0, 0 ), vector( 1, 1, 1 ), 1 );
  977. @\end{verbatim}
  978.  constructs a cone based in the XY parallel plane, centered at the origin
  979.  with radius 1 and with tilted apex at ( 1, 1, 1 ).
  980.    See also CON2.
  981. @\subsubsection{CONVEX}
  982. !CONVEX
  983. @\begin{verbatim}
  984.  PolygonType CONVEX( PolygonType Object )
  985. @\end{verbatim}
  986.    Coerce non convex polygons in {\bf Object}, into convex one. New vertices
  987.  are introduced into the polygonal data during this process. The Boolean
  988.  operations require the input to have convex polygons only (although it may
  989.  return non convex polygons...) and automatically coerced non convex input
  990.  polygons to convex ones, using this same routine.
  991.    However some external tools (like irit2ray, poly3d-r and poly3d-h) requires
  992.  convex polygons. This function may be used on the objects to provide that,
  993.  just before they are being saved into data files. Example:
  994. @\begin{verbatim}
  995.     CnvxObj = CONVEX( Obj );
  996.     save("data", CnvxObj);
  997. @\end{verbatim}
  998.  decompose non convex polygons into convex ones so that data file could be
  999.  used by external tools requiring convex polygons.
  1000. @\subsubsection{CPOLY}
  1001. !CPOLY
  1002. @\begin{verbatim}
  1003.  NumericType CPOLY( PolygonType Polys )
  1004. @\end{verbatim}
  1005.    Returns number of polygons in provided object. Example:
  1006. @\begin{verbatim}
  1007.     DumpLvl = 1
  1008.     NumPolys = CPOLY( Obj );
  1009.     NumPolys;
  1010. @\end{verbatim}
  1011.  prints the number of polygons in object {\bf Obj}.
  1012. @\subsubsection{CRAISE}
  1013. !CRAISE
  1014. @\begin{verbatim}
  1015.  CurveType CRAISE( CurveType Curve, NumericType NewOrder )
  1016. @\end{verbatim}
  1017.    Raise {\bf Curve} to the {\bf NewOrder} Order specified. Currently
  1018.  implemented for Bezier curves of any order and linear Bspline curve only.
  1019.  Example:
  1020. @\begin{verbatim}
  1021.     Crv = ctlpt( E3, 0.0, 0.0, 0.0 ) +
  1022.           ctlpt( E3, 0.0, 0.0, 1.0 ) +
  1023.           ctlpt( E3, 1.0, 0.0, 1.0 );
  1024.     Crv2 = CRAISE( Crv, 4 );
  1025. @\end{verbatim}
  1026.  raises the 90 degrees corner linear Bspline curve {\bf Crv} to be a cubic.
  1027. @\subsubsection{CREFINE}
  1028. !CREFINE
  1029. @\begin{verbatim}
  1030.  CurveType CREFINE( CurveType Curve, NumericType Replace, ListType KnotList )
  1031. @\end{verbatim}
  1032.    Provides the ability to {\bf Replace} a knot vector of {\bf Curve} or refine 
  1033.  it. {\bf KnotList} is a list of knots to refine {\bf Curve} at and all
  1034.  should be within {\bf Curve} parametric domain. If knot vector is to be
  1035.  replaced, the length of {\bf KnotList} should be identical to the length
  1036.  of {\bf Curve} knot vector. If {\bf Curve} is a Bezier curve, it is
  1037.  automatically promoted to be a Bspline curve. Example:
  1038. @\begin{verbatim}
  1039.     Crv2 = CREFINE( Crv, FALSE, list( 0.25, 0.5, 0.75 ) );
  1040. @\end{verbatim}
  1041.  refines {\bf Crv} at the three knots 0.25, 0.5, and 0.75.
  1042. @\subsubsection{CREGION}
  1043. !CREGION
  1044. @\begin{verbatim}
  1045.  CurveType CREGION( CurveType Curve, NumericType MinParam,
  1046.                                                        NumericType MaxParam )
  1047. @\end{verbatim}
  1048.    Extracts a subdomain of {\bf Curve} between {\bf MinParam} and {\bf MaxParam}.
  1049.  Both {\bf MinParam} and {\bf MaxParam} should be within {\bf Curve}
  1050.  parametric domain. Example:
  1051. @\begin{verbatim}
  1052.     SubCrv = CREGION( Crv, 0.3, 0.6 );
  1053. @\end{verbatim}
  1054.  extracts the subdomain of {\bf Crv} from the parameter value 0.3 to the
  1055.  parameter value 0.6.
  1056. @\subsubsection{CROSSEC}
  1057. !CROSSEC
  1058. @\begin{verbatim}
  1059.  PolygonType CROSSEC( PolygonType Object )
  1060. @\end{verbatim}
  1061. ;   Invoke interactive mode to edit/create a polygon in the plane Z = 0. The
  1062. ; polygon must be in the domain [0..1] in X,Y. The first polygon of the given
  1063. ; Object is copied to begin with. If the given {\bf Operand} is NOT a geometric
  1064. ; object, but false (numeric 0.0), a new polygon is created. Returns an (open)
  1065. ; object with this one polygon only and inside side of +Z. Note that if the
  1066. ; given polygon (first polygon of Object) is not on XY plane it is transformed
  1067. ; to it before editing, and transformed back after.
  1068.    Unfortunately, this feature is NOT implemented...
  1069. @\subsubsection{CSURFACE}
  1070. !CSURFACE
  1071. @\begin{verbatim}
  1072.  CurveType CSURFACE( SurfaceType Srf, ConstantType Direction,
  1073.                                                           NumericType Param )
  1074. @\end{verbatim}
  1075.    Extract an iso parametric curve out of {\bf Srf} in the specified
  1076.  {\bf Direction} (ROW or COL) at the specified parameter value {\bf Param}.
  1077.  {\bf Param} must be in {\bf Srf} parameter range in {\bf Direction} direction.
  1078.  The returned curve is {\em in} {\bf Srf}. See also CMESH. Example:
  1079. @\begin{verbatim}
  1080.     Crv = CSURFACE( Srf, COL, 0.15 ); 
  1081. @\end{verbatim}
  1082.  extract an iso parametric curve in the COLumn direction at parameter value
  1083.  0.15 from surface {\bf Srf}.
  1084. @\subsubsection{CTANGENT}
  1085. !CTANGENT
  1086. @\begin{verbatim}
  1087.  VectorType CTANGENT( CurveType Curve, NumericType Param )
  1088. @\end{verbatim}
  1089.    Computes the tangent vector to {\bf Curve} at the parameter value {\bf Param}.
  1090.  Example:
  1091. @\begin{verbatim}
  1092.     Tang = CTANGENT( Crv, 0.5 );
  1093. @\end{verbatim}
  1094.  computes the tangent to {\bf Crv} at the parameter value 0.5.
  1095. @\subsubsection{CTLPT}
  1096. !CTLPT
  1097. @\begin{verbatim}
  1098.  CPt = CTLPT( ConstantType E2, NumericType X, NumericType Y )
  1099.  CPt = CTLPT( ConstantType E3, NumericType X, NumericType Y, NumericType Z )
  1100.  CPt = CTLPT( ConstantType P2, NumericType W, NumericType X, NumericType Y )
  1101.  CPt = CTLPT( ConstantType P3, NumericType W,
  1102.                                NumericType X, NumericType Y, NumericType Z )
  1103. @\end{verbatim}
  1104.    Construct a single control point to be used in curves and surfaces
  1105.  construction. Four types of points may be constructed as follows:
  1106. # 10 2 1 1
  1107.   A two dimensional point with X and Y.
  1108.   A three dimensional point with X, Y, and Z.
  1109.   A two dimensional rational point at X/W, and Y/W.
  1110.   A three dimensional rational point at X/W, Y/W, and Z/W.
  1111.  Example:
  1112. @\begin{verbatim}
  1113.     CPt = CTLPT( E3, 0.0, 0.0, 0.0 );
  1114. @\end{verbatim}
  1115.  constructs an {\bf E3} points at the origin.
  1116. @\subsubsection{CYLIN}
  1117. !CYLIN
  1118. @\begin{verbatim}
  1119.  PolylineType CYLIN( VectorType Center, VectorType Direction,
  1120.                      NumericType Radius )
  1121. @\end{verbatim}
  1122.    Create a CYLINder geometric object, defined by {\bf Center} as CYLIN base center,
  1123.  CYLIN axes {\bf Direction}, and CYLIN base radius {\bf Radius}. Note Direction magnitude
  1124.  also sets the CYLIN height. {\bf Direction} can be any 3D vector.
  1125.    See RESOLUTION for accuracy of CYLIN approximation as polygonal model.
  1126.    Example:
  1127. @\begin{verbatim}
  1128.     Crv = CYLIN( vector( 0, 0, 0 ), vector( 1, 0, 0 ), 10 );
  1129. @\end{verbatim}
  1130.  constructs a cylinder along the X axis from the origin to X = 10.
  1131. @\subsubsection{EXTRUDE}
  1132. !EXTRUDE
  1133. @\begin{verbatim}
  1134.  PolygonType EXTRUDE( PolygonType Object, VectorType Dir )
  1135.  SurfaceType EXTRUDE( CurveType Object, VectorType Dir )
  1136. @\end{verbatim}
  1137.    Creates an extrusion of the given {\bf Object}. If {\bf Object} is a
  1138.  PolygonObject, its first polygon is used as the base for the extrusion in
  1139.  {\bf Dir} direction, and a closed PolygonObject is constrcted. If {\bf Object}
  1140.  is a CurveType, an extrusion surface is constructed instead which is {\em not}
  1141.  a closed object (the two bases of the extrusion are excluded and the curve may
  1142.  be open by itself).
  1143.    No limitation exists on the polygon (can be non-convex), but {\bf Dir}
  1144.  cannot be coplanar with the polygon plane. The curve need not be planar.
  1145.    Example:
  1146. @\begin{verbatim}
  1147.     Cross = cbspline( 3,
  1148.                       list( ctlpt( E2, -0.018, 0.001 ),
  1149.                             ctlpt( E2,  0.018, 0.001 ),
  1150.                             ctlpt( E2,  0.019, 0.002 ),
  1151.                             ctlpt( E2,  0.018, 0.004 ),
  1152.                             ctlpt( E2, -0.018, 0.004 ),
  1153.                             ctlpt( E2, -0.019, 0.001 ) ),
  1154.                       list( KV_OPEN ) );
  1155.     Cross = Cross + -Cross * scale( vector( 1, -1, 1 ) );
  1156.     Napkin = EXTRUDE( Cross * scale( vector( 1.6, 1.6, 1.6 ) ),
  1157.                       vector( 0.02, 0.03, 0.2 ) );
  1158. @\end{verbatim}
  1159.  constructs a closed cross section {\bf Cross} by duplicating a half of
  1160.  it in reverse and merging the two sub-curves. {\bf Cross} is then used as
  1161.  the cross section for the extrusion operation.
  1162. @\subsubsection{GBOX}
  1163. !GBOX
  1164. @\begin{verbatim}
  1165.  PolygonType GBOX( VectorType Point,
  1166.                    VectorType Dx, VectorType Dy, VectorType Dz )
  1167. @\end{verbatim}
  1168.    Create a parallelpiped - Generalized BOX polygonal object, defined by
  1169.  {\bf Point} as base position, and {\bf Dx, Dy, Dz} as 3 3D vectors to define
  1170.  the 6 faces of this generalized BOX. The regular BOX object is special case
  1171.  of GBOX where {\bf Dx} = vector(Dx, 0, 0),   {\bf Dy} = vector(0, Dy, 0),
  1172.  {\bf Dz} = vector(0, 0, Dz).
  1173.    Note {\bf Dx}, {\bf Dy}, {\bf Dz} must be non-coplanar in order to create a feasible object.
  1174.    Example:
  1175. @\begin{verbatim}
  1176.     GB = GBOX(vector(0.0, -0.35, 0.63), vector(0.5, 0.0, 0.5),
  1177.                                         vector(-0.5, 0.0, 0.5),
  1178.                                         vector(0.0, 0.7, 0.0));
  1179. @\end{verbatim}
  1180. @\subsubsection{GPOLYGON}
  1181. !GPOLYGON
  1182. @\begin{verbatim}
  1183.  PolygonType GPOLYGON( GeometryTreeType Object )
  1184. @\end{verbatim}
  1185.    Approximate all Surface(s) in {\bf Object} as polygons using the RESOLUTION
  1186.  and FLAY4PLY variables. The larger RESOLUTION is the more polygons and
  1187.  finer the result approximation will be. Each Bezier patch will have roughly
  1188.  $RESOLUTION^2$ polygons.
  1189.    FLAT4PLY is a Boolean flag controlling the conversion of an (almost) flat
  1190.  patch into four (TRUE) or two (FALSE) polygons. Normals are computed to
  1191.  polygons vertices using surface normal, so Guaroud or Phong rendering can be
  1192.  performed. Returned is a single polygon object, no matter how complex
  1193.  {\bf Object} Hierarchy is. Example:
  1194. @\begin{verbatim}
  1195.     Polys = GPOLYGON( list( Srf1, Srf2, Srf3 ) );
  1196. @\end{verbatim}
  1197.  Converts to polygons the three surfaces {\bf Srf1}, {\bf Srf2}, and {\bf Srf3}.
  1198. @\subsubsection{GPOLYLINE}
  1199. !GPOLYLINE
  1200. @\begin{verbatim}
  1201.  PolylineType GPOLYLINE( GeometryTreeType Object )
  1202. @\end{verbatim}
  1203.    Converts all Surface(s) and Curves(s) in {\bf Object} into polylines using
  1204.  the RESOLUTION variable. The larger RESOLUTION is the finer the result
  1205.  approximation will be. Returned is a single polyline object, no matter
  1206.  how complex {\bf Object} Hierarchy is. Example:
  1207. @\begin{verbatim}
  1208.     Polys = GPOLYLINE( list( Srf1, Srf2, Srf3, list( Crv1, Crv2, Crv3 ) ) );
  1209. @\end{verbatim}
  1210.  converts to polyline the three surfaces {\bf Srf1}, {\bf Srf2}, and {\bf Srf3}
  1211.  and the three curves {\bf Crv1}, {\bf Crv2}, and {\bf Crv3}.
  1212. @\subsubsection{MERGPOLY}
  1213. !MERGEPOLY
  1214. @\begin{verbatim}
  1215.  PolygonType MERGEPOLY( ListType PolyList )
  1216. @\end{verbatim}
  1217.  Merge a set of polygonal objects in {\bf PolyList} list to a single polygonal
  1218.  object. All elements in {\bf ObjectList} must be of PolygonType type. No test
  1219.  is made on the validity of the data. This function performs the same
  1220.  operation as the {\bf \verb+^+} operator would, but may be more convenient
  1221.  to use under some conditions. Example:
  1222. @\begin{verbatim}
  1223.     Vrtx1 = vector( -3, -2, -1 );
  1224.     Vrtx2 = vector( 3, -2, -1 );
  1225.     Vrtx3 = vector( 3, 2, -1 );
  1226.     Vrtx4 = vector( -3, 2, -1 );
  1227.     Poly1 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) ); 
  1228.     Vrtx1 = vector( -3, 2, 1 );
  1229.     Vrtx2 = vector( 3, 2, 1 );
  1230.     Vrtx3 = vector( 3, -2, 1 );
  1231.     Vrtx4 = vector( -3, -2, 1 );
  1232.     Poly2 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );
  1233.     Vrtx1 = vector( -3, -2, 1 );
  1234.     Vrtx2 = vector( 3, -2, 1 );
  1235.     Vrtx3 = vector( 3, -2, -1 );
  1236.     Vrtx4 = vector( -3, -2, -1 );
  1237.     Poly3 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );
  1238.     PolyObj = MERGEPOLY( list( Poly1, Poly2, Poly3 ) );
  1239. @\end{verbatim}
  1240. @\subsubsection{OFFSET}
  1241. !OFFSET
  1242. @\begin{verbatim}
  1243.  CurveType OFFSET( CurveType Crv, NumericType OffsetDistance )
  1244.  SurfaceType OFFSET( SurfaceType Srf, NumericType OffsetDistance )
  1245. @\end{verbatim}
  1246.  Offsets {\bf Crv} or {\bf Srf}, by translating all control points in the
  1247.  curve or surface normal, by the {\bf OffsetDistance} amount. Returned curve
  1248.  or surface only approximates the real offset. One may improve the offset
  1249.  accuracy using refinement. Negative {\bf OffsetDistance} denotes offset in
  1250.  the reversed direction of the normal.
  1251.  Example:
  1252. @\begin{verbatim}
  1253.     OffCrv = OFFSET(Crv, -0.1);
  1254. @\end{verbatim}
  1255.  offsets {\bf Crv} by the amount of $-0.1$ in the reversed normal direction.
  1256. @\subsubsection{POLY}
  1257. !POLY
  1258. @\begin{verbatim}
  1259.  PolygonType POLY( ListType ObjectList )
  1260. @\end{verbatim}
  1261.    Create a single polygon (and therefore open) object, defined by the
  1262.  vertices which respectively defined by the objects in {\bf ObjectList} (see LIST).
  1263.  All elements in {\bf ObjectList} must be of VertorType type. No validity test is
  1264.  made and it is the user responsibility. see CIRCPOLY for conditions applied to
  1265.  open objects. Example:
  1266. @\begin{verbatim}
  1267.     V1  = vector( 0.0, 0.0, 0.0 );
  1268.     V2  = vector( 0.3, 0.0, 0.0 );
  1269.     V3  = vector( 0.3, 0.0, 0.1 );
  1270.     V4  = vector( 0.2, 0.0, 0.1 );
  1271.     V5  = vector( 0.2, 0.0, 0.5 );
  1272.     V6  = vector( 0.3, 0.0, 0.5 );
  1273.     V7  = vector( 0.3, 0.0, 0.6 );
  1274.     V8  = vector( 0.0, 0.0, 0.6 );
  1275.     V9  = vector( 0.0, 0.0, 0.5 );
  1276.     V10 = vector( 0.1, 0.0, 0.5 );
  1277.     V11 = vector( 0.1, 0.0, 0.1 );
  1278.     V12 = vector( 0.0, 0.0, 0.1 );
  1279.     I = poly( list( V1, V2, V3, V4, V5, V6, V7, V8, V9, V10, V11, V12 ) );
  1280. @\end{verbatim}
  1281.  constructs an object with a single polygon in the shape of the I letter.
  1282. @\subsubsection{RULEDSRF}
  1283. !RULEDSRF
  1284. @\begin{verbatim}
  1285.  SurfaceType RULEDSRF( CurveType Crv1, CurveType Crv2 )
  1286. @\end{verbatim}
  1287.    Constructs a ruled surface between the two curves {\bf Crv1} and {\bf Crv2}.
  1288.    Curves do not have to have the same order or type and will be promoted to
  1289.  their least common denominator.
  1290.  Example:
  1291. @\begin{verbatim}
  1292.     Circ = circle( vector( 0.0, 0.0, 0.0 ), 0.25 );
  1293.     Cyl = RULEDSRF( circ, circ * trans( vector( 0.0, 0.0, 1.0 ) ) );
  1294. @\end{verbatim}
  1295.  Constructs a cylinder of radius 0.25 along the Z axis from 0 to 1.
  1296. @\subsubsection{SBEZIER}
  1297. !SBEZIER
  1298. @\begin{verbatim}
  1299.  SurfaceType SBEZIER( ListType CtlMesh )
  1300. @\end{verbatim}
  1301.    Creates a Bezier surface out of the provided control mesh. {\bf CtlMesh} is a
  1302.  list of control points rows, each is a list of control points. All control
  1303.  points must be of the same type (E2, E3, P2, or P3).
  1304.  Example:
  1305. @\begin{verbatim}
  1306.    Srf = SBEZIER( list ( list( ctlpt( E3, 0.0, 0.0, 1.0 ),
  1307.                                ctlpt( E3, 0.0, 1.0, 0.0 ),
  1308.                                ctlpt( E3, 0.0, 2.0, 1.0 ) ),
  1309.                          list( ctlpt( E3, 1.0, 0.0, 0.0 ),
  1310.                                ctlpt( E3, 1.0, 1.0, 2.0 ),
  1311.                                ctlpt( E3, 1.0, 2.0, 0.0 ) ),
  1312.                          list( ctlpt( E3, 2.0, 0.0, 2.0 ),
  1313.                                ctlpt( E3, 2.0, 1.0, 0.0 ),
  1314.                                ctlpt( E3, 2.0, 2.0, 2.0 ) ),
  1315.                          list( ctlpt( E3, 3.0, 0.0, 0.0 ),
  1316.                                ctlpt( E3, 3.0, 1.0, 2.0 ),
  1317.                                ctlpt( E3, 3.0, 2.0, 0.0 ) ),
  1318.                          list( ctlpt( E3, 4.0, 0.0, 1.0 ),
  1319.                                ctlpt( E3, 4.0, 1.0, 0.0 ),
  1320.                                ctlpt( E3, 4.0, 2.0, 1.0 ) ) ) );
  1321. @\end{verbatim}
  1322. @\subsubsection{SBSPLINE}
  1323. !SBSPLINE
  1324. @\begin{verbatim}
  1325.  SurfaceType SBSPLINE( NumericType UOrder, NumericType VOrder,
  1326.                        ListType CtlMesh, ListType KnotVectors )
  1327. @\end{verbatim}
  1328.    Creates a Bspline surface out of the provided {\bf UOrder} and {\bf VOrder}
  1329.  orders, the control mesh {\bf CtlMesh} and the two knot vectors {\bf KnotVectors}.
  1330.  {\bf CtlMesh} is a list of control points rows, each is a list of control
  1331.  points. All control points must be of the same type (E2, E3, P2, or P3).
  1332.  {\bf KnotVectors} is a list of two knot vectors,
  1333.  each is a list of NumericType knots or a list of a single constant KV\_OPEN or
  1334.  KV\_FLOAT in which a uniform knot vector with open or floating end condition
  1335.  will automatically be constructed. Example:
  1336. @\begin{verbatim}
  1337.     Mesh = list ( list( ctlpt( E3, 0.0, 0.0, 1.0 ),
  1338.                         ctlpt( E3, 0.0, 1.0, 0.0 ),
  1339.                         ctlpt( E3, 0.0, 2.0, 1.0 ) ),
  1340.                   list( ctlpt( E3, 1.0, 0.0, 0.0 ),
  1341.                         ctlpt( E3, 1.0, 1.0, 2.0 ),
  1342.                         ctlpt( E3, 1.0, 2.0, 0.0 ) ),
  1343.                   list( ctlpt( E3, 2.0, 0.0, 2.0 ),
  1344.                         ctlpt( E3, 2.0, 1.0, 0.0 ),
  1345.                         ctlpt( E3, 2.0, 2.0, 2.0 ) ),
  1346.                   list( ctlpt( E3, 3.0, 0.0, 0.0 ),
  1347.                         ctlpt( E3, 3.0, 1.0, 2.0 ),
  1348.                         ctlpt( E3, 3.0, 2.0, 0.0 ) ),
  1349.                   list( ctlpt( E3, 4.0, 0.0, 1.0 ),
  1350.                         ctlpt( E3, 4.0, 1.0, 0.0 ),
  1351.                         ctlpt( E3, 4.0, 2.0, 1.0 ) ) );
  1352.     Srf = SBSPLINE( 3, 3, Mesh, list( list( KV_OPEN ),
  1353.                                       list( 3, 3, 3, 4, 5, 6, 6, 6 ) ) );
  1354. @\end{verbatim}
  1355.  constructs a Bspline surface with its first knot vector being uniform with
  1356.  open end condition.
  1357. @\subsubsection{SDIVIDE}
  1358. !SDIVIDE
  1359. @\begin{verbatim}
  1360.  SurfaceType SDIVIDE( SurfaceType Srf, ConstantType Direction,
  1361.                                                           NumericType Param )
  1362. @\end{verbatim}
  1363.    Subdivides a surface into two at the specified parameter value {\bf Param}
  1364.  in the specified {\bf Direction} (ROW or COL). {\bf Srf} can be either a Bspline
  1365.  curve in which {\bf Param} must be within surface parametric domain or a Bezier
  1366.  curve in which {\bf Param} must be in the 0 to 1 range.
  1367.    Returned is a list of the two sub-surfaces. The individual surfaces may be
  1368.  extracted from the list using the {\bf NTH} command. Example:
  1369. @\begin{verbatim}
  1370.     SrfLst = SDIVIDE( Srf, ROW, 0.5 );
  1371.     Srf1 = nth( SrfLst, 1 );
  1372.     Srf2 = nth( SrfLst, 2 );
  1373. @\end{verbatim}
  1374.  subdivides {\bf Srf} at the parameter value of 0.5 in the ROW direction.
  1375. @\subsubsection{SEDITPT}
  1376. !SEDITPT
  1377. @\begin{verbatim}
  1378.  SurfaceType SEDITPT( SurfaceType Srf, CtlPtType CPt, NumericType UIndex,
  1379.                                                       NumericType VIndex )
  1380. @\end{verbatim}
  1381.    Provides a simple mechanism to manually modify a single control point number
  1382.  {\bf UIndex} and {\bf VIndex} (base count is 0) in {\bf Srf} control mesh
  1383.  by substituting {\bf CtlPt} instead. CtlPt must have the same point type as
  1384.  {\bf Srf} points. Original surface {\bf Srf} is not modified. Example:
  1385. @\begin{verbatim}
  1386.     CPt = ctlpt( E3, 1, 2, 3 );
  1387.     NewSrf = SEDITPT( Srf, CPt, 0, 0 );
  1388. @\end{verbatim}
  1389.  constructs a {NewSrf} with the first control point of {\bf Srf} being
  1390.  {\bf CPt}.
  1391. @\subsubsection{SEVAL}
  1392. !SEVAL
  1393. @\begin{verbatim}
  1394.  CtlPtType SEVAL( SurfaceType Srf, NumericType UParam, NumericType VParam )
  1395. @\end{verbatim}
  1396.    Evaluates the provided surface {\bf Srf} at the given {\bf UParam} and
  1397.  {\bf VParam} values. Both {\bf UParam} and {\bf VParam} should be within
  1398.  the surface parametric domain if {\bf Srf} is a Bspline surface, or between 0
  1399.  and 1 if {\bf Srf} is a Bezier surface.  Returned control point has the same
  1400.  type as {\bf Srf} control points. Example:
  1401. @\begin{verbatim}
  1402.     CPt = SEVAL( Srf, 0.25, 0.22 );
  1403. @\end{verbatim}
  1404.  evaluates {\bf Srf} at the parameter values of (0.25, 0.22).
  1405. @\subsubsection{SFROMCRVS}
  1406. !SFROMCRVS
  1407. @\begin{verbatim}
  1408.  SurfaceType SFROMCRVS( ListType CrvList )
  1409. @\end{verbatim}
  1410.    Construct a surface by substituting the curves in {\bf CrvList} as rows
  1411.  in a surface control mesh. Curves in {\bf CrvList} are made compatible
  1412.  by promoting Bezier curves to Bsplines if necessary and raising degree
  1413.  and refining as required before substituting their control polygons as
  1414.  rows in the mesh.
  1415.    The other direction order is the same as the first direction order or
  1416.  if not enough curves are provided equal to the number of curves in {\bf CrvList}.
  1417.    The surface will interpolate the first and last curves only. Example:
  1418. @\begin{verbatim}
  1419.     Crv1 = cbspline( 3,
  1420.                      list( ctlpt( E3, 0.0, 0.0, 0.0 ),
  1421.                            ctlpt( E3, 1.0, 0.0, 0.0 ),
  1422.                            ctlpt( E3, 1.0, 1.0, 0.0 ) ),
  1423.                      list( KV_OPEN ) );
  1424.     Crv2 = Crv1 * trans( vector( 0.0, 0.0, 1.0 ) );
  1425.     Crv3 = Crv2 * scale( vector( 0.0, 0.0, 2.0 ) )
  1426.                 * trans( vector( 0.1, 0.1, 0.1 ) );
  1427.     Srf = SFROMCRVS( list( Crv1, Crv2, Crv3 ) );
  1428. @\end{verbatim}
  1429. @\subsubsection{SNORMAL}
  1430. !SNORMAL
  1431. @\begin{verbatim}
  1432.  VectorType SNORMAL( SurfaceType Srf, NumericType UParam, NumericType VParam )
  1433. @\end{verbatim}
  1434.    Computes the normal vector to {\bf Srf} at the parameter values {\bf UParam}
  1435.  and {\bf VParam}. Example:
  1436. @\begin{verbatim}
  1437.     Tang = SNORMAL( Crv, 0.5, 0.5 );
  1438. @\end{verbatim}
  1439.  computes the normal to {\bf Srf} at the parameter values (0.5, 0.5).
  1440. @\subsubsection{SPHERE}
  1441. !SPHERE
  1442. @\begin{verbatim}
  1443.  PolygonType SPHERE( VectorType Center, NumericType Radius )
  1444. @\end{verbatim}
  1445.    Creates a SPHERE geometric object, defined by {\bf Center} as SPHERE center,
  1446.  and with radius {\bf Radius}.
  1447.    See RESOLUTION for accuracy of SPHERE approximation as polygonal model. 
  1448. @\subsubsection{SRAISE}
  1449. !SRAISE
  1450. @\begin{verbatim}
  1451.  SurfaceType SRAISE( SurfaceType Srf, ConstantType Direction,
  1452.                                                       NumericType NewOrder )
  1453. @\end{verbatim}
  1454.    Raise {\bf Srf} to the specified {\bf NewOrder} Order in the specified
  1455.  direction {\bf Direction}. Currently implemented for Bezier surfaces of
  1456.  any order and linear Bspline surfaces only. Example:
  1457. @\begin{verbatim}
  1458.     Srf = ruledSrf( cbezier( list( ctlpt( E3, -0.5, -0.5, 0.0 ),
  1459.                                    ctlpt( E3,  0.5, -0.5, 0.0 ) ) ),
  1460.                     cbezier( list( ctlpt( E3, -0.5,  0.5, 0.0 ),
  1461.                                    ctlpt( E3,  0.5,  0.5, 0.0 ) ) ) );
  1462.     Srf = SRAISE( SRAISE( Srf, ROW, 3 ), COL, 3 );
  1463. @\end{verbatim}
  1464.  construct a bilinear flat ruled surface and raise its both directions to be
  1465.  quadratic.
  1466. @\subsubsection{SREFINE}
  1467. !SREFINE
  1468. @\begin{verbatim}
  1469.  SurfaceType SREFINE( SurfaceType Srf, ConstantType Direction,
  1470.                       NumericType Replace, ListType KnotList )
  1471. @\end{verbatim}
  1472.    Provides the ability to {\bf Replace} a knot vector of {\bf Srf} or refine 
  1473.  it in the specified direction {\bf Direction} (ROW or COL).
  1474.    {\bf KnotList} is a list of knots to refine {\bf Srf} at. All knots should be
  1475.  within {\bf Srf} parametric domain in {\bf Direction} direction. If knot vector
  1476.  is to be replaced, the length of {\bf KnotList} should be identical to the length
  1477.  of {\bf Srf} knot vector in direction {\bf Direction}. If {\bf Srf} is a
  1478.  Bezier surface, it is automatically promoted to be a Bspline surface.
  1479.  Example:
  1480. @\begin{verbatim}
  1481.     Srf = SREFINE( SREFINE( Srf,
  1482.                             ROW, FALSE, list( 0.333, 0.667 ) ),
  1483.                    COL, FALSE, list( 0.333, 0.667 ) );
  1484. @\end{verbatim}
  1485.  refines {\bf Srf} in both directions by adding two more knots at 0.333 and
  1486.  0.667
  1487. @\subsubsection{SREGION}
  1488. !SREGION
  1489. @\begin{verbatim}
  1490.  SurfaceType SREGION( SurfaceType Srf, ConstantType Direction,
  1491.                                                         NumericType NewOrder )
  1492. @\end{verbatim}
  1493.    Extracts a subdomain of {\bf Srf} between {\bf MinParam} and {\bf MaxParam}
  1494.  in the specified {\bf Direction}. Both {\bf MinParam} and {\bf MaxParam}
  1495.  should be within {\bf Srf} parametric domain in {\bf Direction}.
  1496.  Example:
  1497. @\begin{verbatim}
  1498.     SubSrf = SREGION( Srf, COL, 0.3, 0.6 );
  1499. @\end{verbatim}
  1500.  extracts the subdomain of {\bf Srf} from the parameter value 0.3 to the
  1501.  parameter value 0.6 along the COLumn direction. the ROW direction is
  1502.  extracted as a whole.
  1503. @\subsubsection{STANGENT}
  1504. !STANGENT
  1505. @\begin{verbatim}
  1506.  VectorType STANGENT( SurfaceType Srf, ConstantType Direction,
  1507.                       NumericType UParam, NumericType VParam )
  1508. @\end{verbatim}
  1509.    Computes the tangent vector to {\bf Srf} at the parameter values {\bf UParam}
  1510.  and {\bf VParam} in the direction {\bf Direction}. Example:
  1511. @\begin{verbatim}
  1512.     Tang = STANGENT( Srf, ROW, 0.5, 0.6 );
  1513. @\end{verbatim}
  1514.  computes the tangent to {\bf Srf} in the ROW direction at the parameter
  1515.  values (0.5, 0.6).
  1516. @\subsubsection{SURFREV}
  1517. !SURFREV
  1518. @\begin{verbatim}
  1519.  PolygonType SURFREV( PolygonType Object )
  1520.  SurfaceType SURFREV( CurveType Object )
  1521. @\end{verbatim}
  1522.    Create a surface of revolution by rotating the first polygon/curve of the
  1523.  given {\bf Object}, around the Z axes. No limitation exists on the polygon
  1524.  (can be non-convex), aside from the requirement for it to be non coplanar
  1525.  with a plane of the form Z = Const. No limitation exists for the curve. Use
  1526.  the linear transformation function to position a surface of revolution in a
  1527.  different orientation. Example:
  1528. @\begin{verbatim}
  1529.     VTailAntn = SURFREV( ctlpt( E3, 0.001, 0.0, 1.0 ) +
  1530.                          ctlpt( E3, 0.01,  0.0, 1.0 ) +
  1531.                          ctlpt( E3, 0.01,  0.0, 0.8 ) +
  1532.                          ctlpt( E3, 0.03,  0.0, 0.7 ) +
  1533.                          ctlpt( E3, 0.03,  0.0, 0.3 ) +
  1534.                          ctlpt( E3, 0.001, 0.0, 0.0 ) );
  1535. @\end{verbatim}
  1536.  constructs a piecewise linear Bspline curve in the XZ plane and use it to
  1537.  construct a surface of revolution by rotating it around the Z axis.
  1538. @\subsubsection{SWEEPSRF}
  1539. !SWEEPSRF
  1540. @\begin{verbatim}
  1541.  SurfaceType SWEEPSRF( CurveType CrossSection, CurveType Axis,
  1542.                                                          NumericType Scale )
  1543.  SurfaceType SWEEPSRF( CurveType CrossSection, CurveType Axis,
  1544.                                                          CurveType ScaleCrv )
  1545. @\end{verbatim}
  1546.    Construct a generalized cylinder surface. This function sweeps a specified
  1547.  cross section {\bf CrossSection} along the provided {\bf Axis}.
  1548.  The cross section may be constantly scaled (first form above), or scaled
  1549.  along the Axis parametric domain (second form).
  1550.    No refinement is performed on any of the curves so scaling and axis
  1551.  following result is only approximated. Refinement at the proper location
  1552.  should improve the output accuracy. {\bf ScaleCrv} parametric domain do not
  1553.  have to match the {\bf Axis} parametric domain and their domains are made
  1554.  compatible by this function.
  1555.  Example:
  1556. @\begin{verbatim}
  1557.     Cross = arc( vector( 0.2, 0.0, 0.0 ),
  1558.                  vector( 0.2, 0.2, 0.0 ),
  1559.                  vector( 0.0, 0.2, 0.0 ) ) +
  1560.             arc( vector( 0.0, 0.4, 0.0 ),
  1561.                  vector( 0.1, 0.4, 0.0 ),
  1562.                  vector( 0.1, 0.5, 0.0 ) ) +
  1563.             arc( vector( 0.8, 0.5, 0.0 ),
  1564.                  vector( 0.8, 0.3, 0.0 ),
  1565.                  vector( 1.0, 0.3, 0.0 ) ) +
  1566.             arc( vector( 1.0, 0.1, 0.0 ),
  1567.                  vector( 0.9, 0.1, 0.0 ),
  1568.                  vector( 0.9, 0.0, 0.0 ) ) +
  1569.             ctlpt( E2, 0.2, 0.0 );
  1570.     Axis = arc( vector( -1.0, 0.0, 0.0 ),
  1571.                 vector(  0.0, 0.0, 0.1 ),
  1572.                 vector(  1.0, 0.0, 0.0 ) );
  1573.     Axis = crefine( Arc1, FALSE, list( 0.25, 0.5, 0.75 ) );
  1574.     ScaleCrv = cbezier( list( ctlpt( E2, 0.0, 0.01 ),
  1575.                               ctlpt( E2, 1.0, 0.5 ),
  1576.                               ctlpt( E2, 2.0, 0.01 ) ) );
  1577.     Srf = SWEEPSRF( Cross, Axis, ScaleCrv );
  1578. @\end{verbatim}
  1579.  constructs a rounded rectangle cross section and sweep it along an arc while
  1580.  scaling it so its end points shrink. Note the axis curve {\bf Axis} is
  1581.  manually refined to better approximate the scaling required.
  1582. @\subsubsection{TORUS}
  1583. !TORUS
  1584. @\begin{verbatim}
  1585.  PolygonType TORUS( VectorType Center, VectorType Normal,
  1586.                     NumericType MRadius, NumericType mRadius )
  1587. @\end{verbatim}
  1588.    Create a TORUS polygonal object, defined by {\bf Center} as TORUS center,
  1589.  {\bf Normal} as main TORUS plane normal, {\bf MRadius} as major radius, and
  1590.  {\bf mRadius} as minor.
  1591.    See RESOLUTION for accuracy of TORUS approximation as polygonal model. 
  1592.    Example:
  1593. @\begin{verbatim}
  1594.     T = TORUS( vector( 0.0, 0.0, 0.0), vector( 0.0, 0.0, 1.0), 0.5, 0.2 );
  1595. @\end{verbatim}
  1596.  constructs a torus with major plane as the XY plane, major radius of 0.5,
  1597.  and minor radius of 0.2.
  1598. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  1599. @\subsection{Object transformation functions}
  1600. &Object transformation functions
  1601.  All the routines in this section constructs a 4 by 4 homogeneouos matrix
  1602.  representing the required transform. These matrices may be concatenated to
  1603.  achieve a more complex transforms using the matrix multiplication operator
  1604.  $*$. For example the expression
  1605. @\begin{verbatim}
  1606.     m = trans( vector( -1, 0, 0 ) ) * rotx( 45 ) * trans( vector( 1, 0, 0 ) );
  1607. @\end{verbatim}
  1608.  constructs a transform to rotate an object around the X = 1 line, 45 degrees.
  1609.  A matrix representing the inverse transform can be computed as:
  1610. @\begin{verbatim}
  1611.     InvM = m ^ -1
  1612. @\end{verbatim}
  1613.  See also overloading the - operator.
  1614. @\subsubsection{ROTX}
  1615. !ROTX
  1616. @\begin{verbatim}
  1617.  MatrixType ROTX( NumericType Angle )
  1618. @\end{verbatim}
  1619.    Creates a rotation transformation matrix (around X) with {\bf Angle} degrees.
  1620. @\subsubsection{ROTY}
  1621. !ROTY
  1622. @\begin{verbatim}
  1623.  MatrixType ROTY( NumericType Angle )
  1624. @\end{verbatim}
  1625.    Creates a rotation transformation matrix (around Y) with {\bf Angle} degrees.
  1626. @\subsubsection{ROTZ}
  1627. !ROTZ
  1628. @\begin{verbatim}
  1629.  MatrixType ROTZ( NumericType Angle )
  1630. @\end{verbatim}
  1631.    Creates a rotation transformation matrix (around Z) with {\bf Angle} degrees.
  1632. @\subsubsection{SCALE}
  1633. !SCALE
  1634. @\begin{verbatim}
  1635.  MatrixType SCALE( VectorType ScaleFactors )
  1636. @\end{verbatim}
  1637.    Creates a scaling transformation matrix of {\bf ScaleFactors} scaling factors.
  1638. @\subsubsection{TRANS}
  1639. !TRANS
  1640. @\begin{verbatim}
  1641.  MatrixType TRANS( VectorType TransFactors )
  1642. @\end{verbatim}
  1643.    Creates a translation transformation matrix of {\bf TransFactors} translating
  1644.  amounts.
  1645. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  1646. @\subsection{General purpose functions}
  1647. &General purpose functions  
  1648. @\subsubsection{ALIAS}
  1649. !ALIAS
  1650. @\begin{verbatim}
  1651.  ALIAS( StringType Name, StringType Value )
  1652. @\end{verbatim}
  1653.    Defines a text substitution: each occurrence of {\bf Name} will be replaced by
  1654.  the given {\bf Value}. Unlike the rest of the system, this is CASE SENSITIVE.
  1655.  It is a good practice, therefore, to defines the aliases names to be upper
  1656.  case, and rest of program including alias values in lower case. For example:
  1657. @\begin{verbatim}
  1658.     ALIAS("ED", "edit(\"file.irt\");");
  1659. @\end{verbatim}
  1660.  defines the alias "ED" to be 'edit("file.irt");'. Note the way the double
  1661.  quotes are being escaped.
  1662.    Using "ed" instead of "ED" above will cause infinite loop since "ed"
  1663.  will be expanded for ever... The aliases will be expanded until line is
  1664.  too long or 100 expansions occurred in line.
  1665.    If {\bf Name} is empty string, a list of all defined aliases is printed.
  1666.    If {\bf Name} is not empty, but {\bf Value} is, that alias is deleted. This is
  1667.  the only case you need to specify the alias {\bf Name} in LOWER case (otherwise it
  1668.  will be expanded...) - the alias {\bf Name} comparison is case insensitive.
  1669. @\subsubsection{ATTRIB}
  1670. !ATTRIB
  1671. @\begin{verbatim}
  1672.  ATTRIB( GeometricType Object, StringType Name, StringType Value )
  1673. @\end{verbatim}
  1674.    Provides a mechanism to add a string attribute to a geometric {\bf Object},
  1675.  with name {\bf Name} and value {\bf Value}.
  1676.    These attributes may be used to pass information to other programs about
  1677.  this object and are saved with the objects in data files. For example
  1678. @\begin{verbatim}
  1679.     ATTRIB(Glass, "rgb", "255,0,0");
  1680. @\end{verbatim}
  1681.  sets the rendered color of the {\bf Glass} object. This specific attribute
  1682.  provides a finer control on color setting than provided by the color
  1683.  command, for external programs.
  1684. @\subsubsection{BEEP}
  1685. !BEEP
  1686. @\begin{verbatim}
  1687.  BEEP( NumericType Frequency, NumericType Time )
  1688. @\end{verbatim}
  1689.    Generates a tone with the given {\bf Frequency} (in Hz), for the given period
  1690.  of {\bf Time} (in milliseconds). This command is system dependent and may work
  1691.  differently or not work at all on some systems.
  1692. @\subsubsection{CHDIR}
  1693. !CHDIR
  1694. @\begin{verbatim}
  1695.  CHDIR( StringType NewPath )
  1696. @\end{verbatim}
  1697.    Change current working directory to NewPath (if exists).
  1698.    The entry directory is recovered on exit from program.
  1699. @\subsubsection{CLOSED}
  1700. !CLOSED
  1701. @\begin{verbatim}
  1702.  CLOSED( NumericType Set )
  1703. @\end{verbatim}
  1704.    If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then every polygonal
  1705.  object drawn is assumed to be closed. If a polygonal model is closed every
  1706.  edge is basically drawn twice - once for each adjacent polygon. If the object
  1707.  is assumed closed, every such edge will be drawn once only. By default
  1708.  this option is TRUE.
  1709. @\subsubsection{COLOR}
  1710. !COLOR
  1711. @\begin{verbatim}
  1712.  COLOR( GeometricType Object, NumericType Color )
  1713. @\end{verbatim}
  1714.    Set the color of the object to one of the specified below. Note that an
  1715.  object has a default color (see IRIT.CFG file) according to his origin -
  1716.  loaded with LOAD command, PRIMITIV, or BOOLEAN operation result.
  1717.    The system internally supports colors (although you may have B\&W system)
  1718.  and the colors recognized are:
  1719.  {\bf BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, YELLOW, and WHITE}.
  1720.    See attrib command for more fine control on colors. 
  1721. @\subsubsection{COMMENT}
  1722. !COMMENT
  1723. @\begin{verbatim}
  1724.  COMMENT
  1725. @\end{verbatim}
  1726.  Two types of comments are allowed:
  1727.  1. One lines comment: starts anywhere is a line at the '\#' char up to the
  1728.     end of the line.
  1729.  2. Block comment: starts by the COMMENT keyword follows by a unique
  1730.     character (anything but white space), up to the second occurrence of that
  1731.     character. This is a fast way to comment out large blocks. For example:
  1732. @\begin{verbatim}
  1733.     COMMENT $
  1734.       This is a comment
  1735.     $
  1736. @\end{verbatim}
  1737. @\subsubsection{DIR}
  1738. @\begin{verbatim}
  1739.  DIR( StringType MatchPattern )
  1740. @\end{verbatim}
  1741.    Print the files match the MatchPattern in the current working directory.
  1742.    MatchPattern may have wild characters as in regular dos DIR - '*', '?'.
  1743.    This command is only supported under the MSDOS implementation. Example:
  1744. @\begin{verbatim}
  1745.     DIR( "*.irt" );
  1746. @\end{verbatim}
  1747.  lists all the '.irt' files in the current directory.
  1748. @\subsubsection{EDIT}
  1749. !EDIT
  1750. @\begin{verbatim}
  1751.  EDIT( StringType FileName )
  1752. @\end{verbatim}
  1753.    Invoke the editor (defined in the IRIT.CFG configuration file) as a child
  1754.  process if the solid modeler. Only one parameter is passed to the editor
  1755.  which is the FileName to edit. As the solid modeler is still resident, the
  1756.  child process (the editor) will get only the remained memory - as seen by
  1757.  the core left.
  1758.    This command is only supported under the MSDOS implementation.
  1759. @\subsubsection{EXIT}
  1760. !EXIT
  1761. @\begin{verbatim}
  1762.  EXIT();
  1763. @\end{verbatim}
  1764.    Exits from the solid modeler. NO warning is given!
  1765. @\subsubsection{FOR}
  1766. @\begin{verbatim}
  1767.  FOR( NumericType Start, NumericType Increment, NumericType End, AnyType Body )
  1768. @\end{verbatim}
  1769.    Execute the {\bf Body} (see below), while the FOR loop conditions hold.
  1770.    {\bf Start, Increment, End} are evaluated first and the loop will be executed
  1771.  while {\bf $<=$ End} if {\bf Increment $>$ 0} or while {\bf $>=$ End} if {\bf Increment $<$ 0}.
  1772.    If {\bf Start} is of the form "(Variable = Expression)" then that variable is
  1773.  updated on each iteration, and can be used within the body.
  1774.    The body may consist of any number of regular commands, separated by
  1775.  COLONs, including nesting FOR loops to arbitrary level.
  1776.    No new variables should be introduced in loops - Use only old
  1777.  variables and/or the iteration variable defined in {\bf Start} (that makes it
  1778.  a feature now...). Example:
  1779. @\begin{verbatim}
  1780.     FOR ( (b = 100), 100, 300,
  1781.         FOR ( (a = 100), 100, 2000,
  1782.                 (
  1783.                   beep(a, b)
  1784.                 )
  1785.             )
  1786.         );
  1787. @\end{verbatim}
  1788.  exercises the BEEP function in different durations and different frequencies.
  1789.  This will best work under MSDOS systems.
  1790. @\subsubsection{FREE}
  1791. !FREE
  1792. @\begin{verbatim}
  1793.  FREE( GeometricType Object )
  1794. @\end{verbatim}
  1795.    Because of the usually huge size of geometric objects, this procedure
  1796.  may be used to free them. Note however that reassigning a value (even
  1797.  of different type) will automatically release old allocated space as well.
  1798. @\subsubsection{HELP}
  1799. !HELP
  1800. @\begin{verbatim}
  1801.  HELP( StringType Subject )
  1802. @\end{verbatim}
  1803.    Provides help on the specified Subject. Example:
  1804. @\begin{verbatim}
  1805.     HELP("");
  1806. @\end{verbatim}
  1807.  will list all {\em IRIT} commands.
  1808. @\subsubsection{IF}
  1809. @\begin{verbatim}
  1810.  IF( NumericType Left, StringType Cond, NumericType Right, AnyType Body )
  1811. @\end{verbatim}
  1812.    Executes {\bf Body} (group of regular commands, separated by COLONs - see FOR)
  1813.  if the condition holds: {\bf Left} and {\bf Right} are evaluated and tested against
  1814.  the specified condition {\bf Cond} which may be: "$=$", "$>$", "$<$", "$<>$", "$>=$", "$<=$".
  1815.    Example:
  1816. @\begin{verbatim}
  1817.     resolution = 10;
  1818.     IF ( machine, "=", msdos, ( resolution = 5 ) );
  1819. @\end{verbatim}
  1820.  sets the resolution to be 10 unless running on an MSDOS system in which the
  1821.  resolution variable will be set to 5.
  1822. @\subsubsection{INCLUDE}
  1823. !INCLUDE
  1824. @\begin{verbatim}
  1825.  INCLUDE( StringType FileName )
  1826. @\end{verbatim}
  1827.    Executes the script file {\bf FileName}. Nesting of include file is allowed up
  1828.  to 10 levels deep. If error occurs, all open files in all nested files
  1829.  are closed and data is expected at the top level (standard input).
  1830.    A script file can contain any command the solid modeler supports. Example:
  1831. @\begin{verbatim}
  1832.     INCLUDE( "general.irt" );
  1833. @\end{verbatim}
  1834.  includes the file "general.irt".
  1835. @\subsubsection{INTERACT}
  1836. !INTERACT
  1837. @\begin{verbatim}
  1838.  INTERACT( GeometryTreeType Object, NumericType UpdateViewMat )
  1839. @\end{verbatim}
  1840.    Invoke interactive mode to manipulate (transform) the given (geometric)
  1841.  {\bf Object}. {\bf Object} may be any GeometricType or a list of other
  1842.  GeometryTypes nested to an arbitrary level. {\bf Object} is displayed as
  1843.  a wire frame. ON SGI 4D systems a rendered display is also available.
  1844.    If {\bf UpdateViewMat} is non zero (see TRUE/FALSE and ON/OFF) then the
  1845.  global viewing matrix VIEW\_MAT is updated to the last view from INTERACT.
  1846.    INTERACT open an interactive menu to rotate/translate/scale an object(s).
  1847.  Each transformation has zero influence in middle of its box, and maximum
  1848.  (and opposite) on the box left and right ends.
  1849.    Screen transformation transforms according to the screen - X is horizontal,
  1850.  Y vertical, Z into screen. Object transformation transform in object own
  1851.  coordinate system - you probably want to display AXES object with it (see
  1852.  AXES).
  1853.    Left mouse button (return) is used to EXECUTE transformation. Right mouse
  1854.  button (space bar) is used to ABORT long display in the middle.
  1855.    On MSDOS, use the numeric keyboard pad (with/without shift) to move if no
  1856.  mouse available.
  1857.    If {\bf Object} is a GeometricType, that object is being displayed. If
  1858.  however it is an ListType the list is recursively traversed and all
  1859.  geometric objects within the list are displayed. Non geometric object in
  1860.  the list are ignored.
  1861. @\begin{verbatim}
  1862.  INTERACT( list( Axes, Obj ), FALSE );
  1863. @\end{verbatim}
  1864.  displays and interact with the object {\bf Obj} and the predefined object
  1865.  {\bf Axes}. VIEW\_MAT will not be updated once INTERACT is done.
  1866. @\subsubsection{LIST}
  1867. !LIST
  1868. @\begin{verbatim}
  1869.  ListType LIST( AnyType Elem1, AnyType Elem2, ... )
  1870. @\end{verbatim}
  1871.    Constructs an object as a list of several other objects. Only a reference
  1872.  is made to the Elements, so modifying Elem1 after being included in list,
  1873.  will affect Elem1 in that list, next time list is used!
  1874.    Each inclusion of an object in a list increases its internal {\bf used}
  1875.  reference. The object is freed iff in {\bf used} reference is zero.
  1876.    As a result, attempt to delete a variable (using FREE) which is referenced
  1877.  in a list will remove the variable, but the object itself will be freed only
  1878.  when that list will be freed.
  1879. @\subsubsection{LOAD}
  1880. !LOAD
  1881. @\begin{verbatim}
  1882.  AnyType LOAD( StringType FileName )
  1883. @\end{verbatim}
  1884.    Load the object from the given {\bf FileName}. The object may be any object
  1885.  defined in the system, including lists, in which the structure is
  1886.  loaded recursively and reconstructed as well (internal objects are
  1887.  inserted into the global system object list if have names defined).
  1888.    If no file type is provided, ".dat" is assumed.
  1889. @\subsubsection{LOGFILE}
  1890. !LOGFILE
  1891. @\begin{verbatim}
  1892.  LOGFILE( NumericType Set )
  1893. @\end{verbatim}
  1894.    If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then everything printed in
  1895.  the input window, will go to the log file specified in IRIT.CFG configuration
  1896.  file. This file will be created the first time logfile is turned ON.
  1897. @\subsubsection{NORMAL}
  1898. !NORMAL
  1899. @\begin{verbatim}
  1900.  NORMAL( NumericType Set, NumericType Size, NumericType Color )
  1901. @\end{verbatim}
  1902.    If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then the normals to the
  1903.  objects are also displayed. Normals should always point INTO the object.
  1904.    {\bf Size} sets the length of the normals, and {\bf Color} their color.
  1905.  See COLOR command for legal colors.
  1906. @\subsubsection{NTH}
  1907. @\begin{verbatim}
  1908.  AnyType NTH( ListType ListObject, NumericType Index )
  1909. @\end{verbatim}
  1910.  Returns the {\bf Index} (base count 1) element of the list {\bf ListObject}.
  1911.  Example:
  1912. @\begin{verbatim}
  1913.     Lst = list( a, list( b, c ), d );
  1914.     Lst2 = NTH( Lst, 2 );
  1915. @\end{verbatim}
  1916.  and now {\bf Lst2} is equal to 'list( b, c )'.
  1917. @\subsubsection{PAUSE}
  1918. !PAUSE
  1919. @\begin{verbatim}
  1920.  PAUSE( NumericType Flush )
  1921. @\end{verbatim}
  1922.    Waits for a keystroke. Nice to have if temporary stopping in middle of
  1923.  included file (see INCLUDE) is needed. If {\bf Flush} is TRUE then the input
  1924.  is first flushed to guarantee we will wait.
  1925.    The implementation of this function is machine dependent and is geared
  1926.  mainly for MSDOS.
  1927. @\subsubsection{SAVE}
  1928. !SAVE
  1929. @\begin{verbatim}
  1930.  SAVE( StringType FileName, AnyType Object )
  1931. @\end{verbatim}
  1932.    Saves the provided {\bf Object} into specified file {\bf FileName}. No extension type
  1933.  is needed (ignored if specified), and ".dat" is always used. {\bf Object} can
  1934.  be any object type including list, in which structure is saved recursively. 
  1935.  See also LOAD.
  1936. @\subsubsection{SNOC}
  1937. !SNOC
  1938. @\begin{verbatim}
  1939.  SNOC( AnyType Object, ListType ListObject )
  1940. @\end{verbatim}
  1941.    Similar to the lisp cons operator but puts the new {\bf Object} in the {\em end}
  1942.  of the list {\bf ListObject} instead of the beginning, in place. Example:
  1943. @\begin{verbatim}
  1944.     Lst = list( axes );
  1945.     SNOC( Srf, Lst );
  1946. @\end{verbatim}
  1947.  and now {\bf Lst} is equal to the list 'list( axes, Srf )'.
  1948. @\subsubsection{SYSTEM}
  1949. !SYSTEM
  1950. @\begin{verbatim}
  1951.  SYSTEM()
  1952. @\end{verbatim}
  1953.    Invoke the current command processor (usually COMMAND.COM) as defined by
  1954.  the COMSPEC environment variable. As the solid modeler is still resident,
  1955.  the child process (the command processor) will get only the remained memory
  1956.  - as seen by the core left.
  1957.    This command is only supported under the MSDOS implementation.
  1958. @\subsubsection{TIME}
  1959. !TIME
  1960. @\begin{verbatim}
  1961.  TIME( NumericType Reset )
  1962. @\end{verbatim}
  1963.    Returns the real time (in seconds) from the last time TIME was called with
  1964.  {\bf Reset} TRUE. Note this is real time and not cpu time so running in a multi
  1965.  tasked system will return values, which not necessarily reflects this program
  1966.  execution time. As mentioned above if {\bf Reset} is non zero the time count is
  1967.  reset. The time is automatically reset to beginning of execution of this
  1968.  program, when the program is first invoked.
  1969.    Since this is real type, it may be unusable for multitasked systems.
  1970.  Example:
  1971. @\begin{verbatim}
  1972.     Time1 = TIME( TRUE );
  1973.       .
  1974.       .
  1975.       .
  1976.     Time1 = TIME( FALSE );
  1977.     DumpLvl = 1;
  1978.     Time1;
  1979. @\end{verbatim}
  1980.  prints the time in seconds between the above two time function calls.
  1981. @\subsubsection{VARLIST}
  1982. !VARLIST
  1983. @\begin{verbatim}
  1984.  VARLIST()
  1985. @\end{verbatim}
  1986.    List all the currently defined objects in the system.
  1987. @\subsubsection{VECTOR}
  1988. !VECTOR
  1989. @\begin{verbatim}
  1990.  VectorType VECTOR( NumericType Operand1, NumericType Operand2,
  1991.                                                        NumericType Operand3 )
  1992. @\end{verbatim}
  1993.    Creates a vector type object, out of 3 NumericType scalars.
  1994. @\subsubsection{VIEW}
  1995. !VIEW
  1996. @\begin{verbatim}
  1997.  VIEW( GeometricTreeType Object, NumericType ClearWindow )
  1998. @\end{verbatim}
  1999.    Display the (geometric) object(s) as given in {\bf Object}. See INTERACT
  2000.  for more on {\bf Object}.
  2001.    If {\bf ClearWindow} is non zero (see TRUE/FALSE and ON/OFF) the window is
  2002.  first cleared (before drawing the objects).
  2003.    The global viewing matrix VIEW\_MAT is used as the transformation matrix.
  2004.    Example:
  2005. @\begin{verbatim}
  2006.     VIEW( Axes, FALSE );
  2007. @\end{verbatim}
  2008.  displays the predefined object {\bf Axes} in the viewing window on top of
  2009.  what was drawn there.
  2010. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2011. @\subsection{System variables}
  2012. &System variables
  2013.  System variables are predefined objects in the system. Any time {\em IRIT} is
  2014.  executed, these variable will exist and be set to values which are sometimes
  2015.  machine dependent. These are {\em regular} objects in any other sense
  2016.  including the ability to delete or overwrite them. One can modify, delete
  2017.  or introduce other objects by the use of the IRITINIT.IRT file.
  2018. @\subsubsection{AXES}
  2019. !AXES
  2020.    Predefined polyline object (PolylineType) that holds XYZ axes system. May be
  2021.  viewed.
  2022. @\subsubsection{DRAWCTLPT}
  2023. !DRAWCTLPT
  2024.    Predefined Boolean variable (NumericType) controlling whether curves control
  2025.  polygons and surfaces control meshes will be drawn (TRUE) or not (FALSE). 
  2026. @\subsubsection{DUMPLVL}
  2027. !DUMPLVL
  2028.    Content of objects assigned to variables may be displayed by executing the
  2029.  command 'objname;' where objname is the name of the object. This variable
  2030.  (NumericType) control the way the data is dumped as follows:
  2031. # 20 2 1 1
  2032.  DumpLvl $>=$ 0
  2033.   Only object names/types are printed.
  2034.  DumpLvl $>=$ 1
  2035.   Non geometric object values are dumped.
  2036.  DumpLvl $>=$ 2
  2037.   Curves and Surfaces are dumped.
  2038.  DumpLvl $>=$ 3
  2039.   Polygons/lines are dumped.
  2040.  DumpLvl $>=$ 4
  2041.   List objects are traversed recursively.
  2042. @\subsubsection{ECHOSRC}
  2043. !ECHOSRC
  2044.    Predefined Boolean variable (NumericType) controlling echoing of
  2045.  interpreted commands to screen (TRUE) or not (FALSE).
  2046. @\subsubsection{FLAT4PLY}
  2047. !FLAT4PLY
  2048.    Predefined Boolean object (NumericType) controlling the way almost flat
  2049.  surface patches are converted to polygons: four polygons (TRUE) or only
  2050.  two polygons (FALSE).
  2051. @\subsubsection{INTERCRV}
  2052. !INTERCRV
  2053.    Predefined numeric object (NumericType) that if TRUE the Boolean geometry
  2054.  operators return the intersection curves instead of the result model.
  2055.    Its default value is FALSE.
  2056. @\subsubsection{INTERNAL}
  2057. !INTERNAL
  2058.    Predefined Boolean object (NumericType) that if not zero enables displaying
  2059.  internal polygon edges (edges created by the convex polygon splitting for
  2060.  example). One usually does not want to see these edges, and its default
  2061.  value is FALSE.
  2062. @\subsubsection{MACHINE}
  2063. !MACHINE
  2064.    Predefined numeric object (NumericType) holding machine type as one of the
  2065.  following constants: MSDOS, SGI, HP, SUN, APOLLO, UNIX.
  2066. @\subsubsection{RESOLUTION}
  2067. !RESOLUTION
  2068.    Predefined numeric object (NumericType) that sets the accuracy of the
  2069.  primitive geometric objects generated. Holds the number of divisions a
  2070.  circle is divided into (with minimum value of 4). If, for example, is set
  2071.  to 6, then a CONE generated, will effectively be 6 sided pyramid.
  2072.    Also controls the fineness freeform curves and surfaces are approximated
  2073.  as piecewise linear polylines (for display purposes for example), and the
  2074.  fineness freeform surfaces are approximated as polygons.
  2075. @\subsubsection{VIEW\_MAT}
  2076. !VIEW_MAT
  2077.    Predefined matrix object (MatrixType) to hold the viewing matrix used/set
  2078.  by VIEW and/or INTERACT.
  2079. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2080. @\subsection{System constants}
  2081. &System constants
  2082.  The following constants are used by the various functions of the system to
  2083.  signal certain conditions. Internally, they are represented numerically
  2084.  although, in general, their exact value is unimportant and may be changed
  2085.  in future versions. In the rare situation you would like to know their
  2086.  values, here is a sequence that will allow you to do so:
  2087. @\begin{verbatim}
  2088.     DumpLvl = 1;
  2089.     A = BLUE;
  2090.     A;
  2091. @\end{verbatim}
  2092.  in other words, assign the constant to a variable and display its content.
  2093. @\subsubsection{APOLLO}
  2094. !APOLLO
  2095.  A constant designates an APOLLO system in the MACHINE variable.
  2096. @\subsubsection{BLACK}
  2097. !BLACK
  2098.  A constant defining a BLACK color.
  2099. @\subsubsection{BLUE}
  2100. !BLUE
  2101.  A constant defining a BLUE color.
  2102. @\subsubsection{COL}
  2103.  A constant defining the COLumn direction of a surface mesh.
  2104. @\subsubsection{CYAN}
  2105. !CYAN
  2106.  A constant defining a CYAN color.
  2107. @\subsubsection{E2}
  2108.  A constant defining an E2 (X and Y coordinates) control point type.
  2109. @\subsubsection{E3}
  2110.  A constant defining an E3 (X, Y, and Z coordinates) control point type.
  2111. @\subsubsection{FALSE}
  2112. !FALSE
  2113.  A zero constant. May be used as Boolean operand.
  2114. @\subsubsection{GREEN}
  2115. !GREEN
  2116.  A constant defining a GREEN color.
  2117. @\subsubsection{HP}
  2118.  A constant designates an HP system in the MACHINE variable.
  2119. @\subsubsection{KV\_FLOAT}
  2120. !KV_FLOAT
  2121.  A constant defining a floating end condition uniform knot vector.
  2122. @\subsubsection{KV\_OPEN}
  2123. !KV_OPEN
  2124.  A constant defining an open end condition uniform knot vector.
  2125. @\subsubsection{MAGENTA}
  2126. !MAGENTA
  2127.  A constant defining a MAGENTA color.
  2128. @\subsubsection{MSDOS}
  2129. !MSDOS
  2130.  A constant designates an MSDOS system in the MACHINE variable.
  2131. @\subsubsection{OFF}
  2132.  Synonym of FALSE.
  2133. @\subsubsection{ON}
  2134.  Synonym for TRUE.
  2135. @\subsubsection{P2}
  2136.  A constant defining an P2 (X, Y, and W coordinates) rational control point
  2137.  type.
  2138. @\subsubsection{P3}
  2139.  A constant defining an P3 (X, Y, Z, and W coordinates) rational control
  2140.  point type.
  2141. @\subsubsection{PI}
  2142.  The constant of 3.141592...
  2143. @\subsubsection{RED}
  2144.  A constant defining a RED color.
  2145. @\subsubsection{ROW}
  2146.   A constant defining the ROW direction of a surface mesh.
  2147. @\subsubsection{SGI}
  2148.  A constant designates a SGI system in the MACHINE variable.
  2149. @\subsubsection{SUN}
  2150.  A constant designates a SUN system in the MACHINE variable.
  2151. @\subsubsection{TRUE}
  2152. !TRUE
  2153.  A non zero constant. May be used as Boolean operand.
  2154. @\subsubsection{UNIX}
  2155. !UNIX
  2156.  A constant designates a generic UNIX system in the MACHINE variable.
  2157. @\subsubsection{WHITE}
  2158. !WHITE
  2159.  A constant defining a WHITE color.
  2160. @\subsubsection{YELLOW}
  2161. !YELLOW
  2162.  A constant defining a YELLOW color.
  2163. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2164. @\section{poly3d - A Data Display Program}
  2165. !poly3d - A Data Display Program
  2166. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2167. @\subsection{Introduction}
  2168. &Introduction
  2169.  poly3d is a display program for data files created by the {\em IRIT} solid
  2170.  modeler. Data can be displayed on almost any IBMPC graphic device that has
  2171.  Borland's BGI support, for the MSDOS BC++ port, or using any device driver
  2172.  that is supported by DJGPP, in the MSDOS DJGPP port.
  2173.    Under UNIX systems both MIT's X11 and SGI's GL are supported.
  2174.    On SGI's, solid smooth shading is available via normal computation
  2175.  support. Displayed images may be saved as postscript files as well as GIF
  2176.  images (if poly3d was built with GIF support).
  2177. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2178. @\subsection{Command Line Options}
  2179. &Command line options
  2180. @\begin{verbatim}
  2181.  poly3d [-c] [-m] [-i] [-e #Edges] [-n] [-N] [-M] [-I n] [-P] [-S n]
  2182.                                                 [-f FineNess] [-4] [-z] DFiles
  2183. @\end{verbatim}
  2184. @\begin{itemize}
  2185. @\item
  2186.   {\bf -c}: Closed object - if an object is closed (such as objects created by
  2187.        {\em IRIT} solid medeller) each edge is actually displayed twice - once
  2188.        for each adjacent polygon. This flag will ensure every edge will be
  2189.        displayed only once.
  2190. @\item
  2191.   {\bf -m}: More - provide some more information on the data file(s) parsed.
  2192. @\item
  2193.   {\bf -i}: Internal edges (created by {\em IRIT}) - default is not to display them, and
  2194.        this option will force displaying them as well.
  2195. @\item
  2196.   {\bf -e n}: \# Edges to use from each given polygon (default all). Very handy to
  2197.        do '-e 2 -4-' or '-e 1 -4' on polygons created from a freeform surface.
  2198. @\item
  2199.   {\bf -n}: Draw vertex normals if data file has them.
  2200. @\item
  2201.   {\bf -N}: Draw polygon normals if data file has them (PLANE definition).
  2202. @\item
  2203.   {\bf -M}: Draw the surfaces control mesh/curves control polygons as well.
  2204. @\item
  2205.   {\bf -I n}: Specify number of isolines per surface.
  2206. @\item
  2207.   {\bf -P}: Generate polygonal approximation for surfaces instead of isolines.
  2208. @\item
  2209.   {\bf -S n}: Specify the log based 2 of number of samples per curve.
  2210. @\item
  2211.   {\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
  2212.        This number is log based 2 of roughly the number of subdivisions of
  2213.        the surface in each axes (see cagd\_lib for more).
  2214. @\item
  2215.   {\bf -4}: Force four polygons per flat bilinear in surface to polygon
  2216.        conversion. Otherwise two polygons only.
  2217. @\item
  2218.   {\bf -z}: Print version number and current defaults.
  2219. @\end{itemize}
  2220.    Some of the options may be turned on in poly3d.cfg. They can be then turned
  2221.  off in the command line as -?-.
  2222. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2223. @\subsection{Configuration}
  2224. &Configuration
  2225.    The program can be configured using a configuration file named poly3d.cfg.
  2226.    The appropriate configuration file should be copied into poly3d.cfg:
  2227.    Under MSDOS BC++ its poly3dms.cfg, under MSDOS DJGPP its poly3ddj.cfg, and
  2228.  under UNIX its poly3dun.cfg.
  2229.    This is a plain ascii file you can edit directly and set the parameters
  2230.  according to the comments there. Executing 'poly3d -z' will show the
  2231.  current configuration as read from the configuration file.
  2232.    MSDOS version only:
  2233.    The configuration file in MSDOS BC++ system can be in any directory which
  2234.  is in your path - the same place as the executable is probably a good choice.
  2235.    The program supports SuperVGA, VGA/EGA, CGA \& HERCULES graphics card, and
  2236.  uses the Turbo C autodetect feature. If this fails you can always coerce it
  2237.  to a specific card - see the poly3d.cfg file. For a SuperVGA you will need to
  2238.  provide your own BGI driver.
  2239.    The program will use 80x87 if it detects one - again uses the Turbo C 80x87
  2240.  autodetect, or will run (much!) slower without it...
  2241.    The MSDOS DJGPP port can be used with any graphics driver that DJGPP
  2242.  support. If not 80x87 is present, the emulator, emu387, must be used. 
  2243.    In both the BC++ and DJGPP ports, a mouse or a joystick may be used
  2244.  if properly selected in poly3d.cfg configuration file.
  2245.    A windowing library, called intr\_lib is used (for both BC++ and DJGPP)
  2246.  for the interaction and windows which can be resized/moved/poped/pushed etc.
  2247.  via a default setting as selected by the configuration file and modified via
  2248.  a pop up menu during a session. see Irit solid modeler for more on intr\_lib
  2249.  and the interface.
  2250.    UNIX version only:
  2251.    The configuration file is being searched in the IRIT\_PATH environment
  2252.  variable under UNIX hosts. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
  2253.    Note IRIT\_PATH must terminate with '/'. If the variables is not set only
  2254.  the current directory is being searched.
  2255.    Add the following options to your {\em .Xdefaults} if you use X11. Most options
  2256.  set are self explanatory. The Trans attributes control the transformation
  2257.  window, while View control the view window. SubWin control the subwindows
  2258.  within the Transformation window:
  2259. # 33 2 0 1
  2260.  poly3d*Trans*BackGround:
  2261.   NavyBlue
  2262.  poly3d*Trans*BorderColor:
  2263.   Red
  2264.  poly3d*Trans*BorderWidth:
  2265.  poly3d*Trans*TextColor:
  2266.   Yellow
  2267.  poly3d*Trans*SubWin*BackGround:
  2268.   DarkGreen
  2269.  poly3d*Trans*SubWin*BorderColor:
  2270.   Magenta
  2271.  poly3d*Trans*Geometry:
  2272.   =150x500+500+0
  2273.  poly3d*Trans*CursorColor:
  2274.   Green
  2275.  poly3d*View*BackGround:
  2276.   NavyBlue
  2277.  poly3d*View*BorderColor:
  2278.   Red
  2279.  poly3d*View*BorderWidth:
  2280.  poly3d*View*Geometry:
  2281.   =500x500+0+0
  2282.  poly3d*View*CursorColor:
  2283.   Red
  2284.    Note the above options are the same as for the irit solid modeler
  2285.  itself.
  2286.    If poly3d is used under SGI gl library, you can set the prefered windows
  2287.  location in poly3d.cfg. No color control is provided at this time.
  2288. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2289. @\subsection{Usage}
  2290. &Usage
  2291.    The program is controlled via a transformation menu. The object can be
  2292.  rotated, translated, or scaled in screen or object based corrdinate system
  2293.  and with orthographic or perspective projected.
  2294.   Two operations are fundamental to the operation of poly3d:
  2295. # 10 2 0 1
  2296.  EXECUTE
  2297.   $<$Return$>$ key on the keyboard, or left  mouse button if exists.
  2298.  ABORT
  2299.   $<$Space$>$  key on the keyboard, or right mouse button if exists.
  2300.    The cursor may be moved via a mouse (if exists) or using the numeric
  2301.  keypad/arrows (shifted for faster movement).
  2302.    The ABORT may be useful in large data sets when another
  2303.  transformation should be applied with no need to wait to the current one to
  2304.  complete.
  2305.    The menus work in two modes in all implementations. If you click the
  2306.  EXECUTE button once on a transformation subwindow, that transformation
  2307.  will be applied. Most transformation subwindows have vertical bars in
  2308.  the middle. If the cursor is on the vertical bar the {\em amout} of
  2309.  transformation applied is {\em zero}. If the cursor is on the leftmost side
  2310.  of the subwindow, the {\em amount} will be maximized and if the cursor is on
  2311.  the rightmost side, the transformation {\em amount} will be maximized to the
  2312.  other direction (inverse transform).
  2313.    In addition, if one clicks the mouse (with the affect as above) but hold
  2314.  the EXECUTE button while dragging, continuous transformation will be applied.
  2315.  Altough implemented in all systems, you would probably like to try this on
  2316.  very simplistic models on slow machines.
  2317.    Keyboard control support is for MSDOS systems only.
  2318. @\subsection{Output Files}
  2319. &Output Files
  2320.    poly3d can save viewing matrices (to be used by poly3d-h, poly3d-r, or
  2321.  irit2ray for example), postscript files of the current view and GIF images
  2322.  of the screen if poly3d was built with GIF support.
  2323.    The postscript file can be directly sent to a laser printer. The viewing
  2324.  matrix should be appended {\em after} the data when any program is to use
  2325.  it. The last viewing matrix in the data will be the one used. For example
  2326. @\begin{verbatim}
  2327.  irit2ray -l -f 20 b58.dat generic0.mat
  2328. @\end{verbatim}
  2329.  where generic0.mat is the matrix saved bu poly3d.
  2330.    All files will be named genericX.EXT where EXT can be one of '.mat', '.ps'
  2331.  and '.gif' respectively. X is single digit so up to 10 distinguished files
  2332.  of each type can be saved each time.
  2333. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2334. @\section{poly3d-h - Hidden Line Removing Program}
  2335. !poly3d-h - Hidden Line Removing Program
  2336. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2337. @\subsection{Introduction}
  2338. &Introduction
  2339.     poly3d-h is a program to remove hidden line of a given polygonal model.
  2340.  Freeform objects are preprocessed into polygons with controlled fineness.
  2341.     The program performes 4 passes over the input:
  2342.  1. Preprocesses and maps all polgons in scene, and sorts them.
  2343.  2. Generates edges out of the polygonal model and sorts them (preprocesing
  2344.     for the scan line algorithm) into buckets.
  2345.  3. Intersects edges, and splits edges with non homogeneous visibility (the
  2346.     scan line algorithm)
  2347.  4. Applies a visibility test of each edge.
  2348.         This programs can handle CONVEX polygons only. From {\em IRIT} one can
  2349.  ensure a model is consisting of convex polygons only by the CONVEX command:
  2350. @\begin{verbatim}
  2351.   CnvxObj = convex( Obj );
  2352. @\end{verbatim}
  2353.  just before saving it into a file. Surfaces are always decomposed into
  2354.  triangles only.
  2355.     poly3d-h output is of the form of polylines. It is a regular {\em IRIT} data
  2356.  file that can be viewed using poly3d, for example.
  2357. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2358. @\subsection{Command Line Options}
  2359. &Command line options
  2360. @\begin{verbatim}
  2361.  poly3d-h [-b] [-m] [-i] [-e #Edges] [-f FineNess] [-4] [-z] DFiles [> OutFile]
  2362. @\end{verbatim}
  2363. @\begin{itemize}
  2364. @\item
  2365.   {\bf -b}: BackFacing - if object is closed (such as most models created by {\em IRIT})
  2366.        back facing polygons will be deleted, and therefore speed up the
  2367.        process by at list factor of two.
  2368. @\item
  2369.   {\bf -m}: More - provide some more information on the data file(s) parsed.
  2370. @\item
  2371.   {\bf -i}: Internal edges (created by {\em IRIT}) - default is not to display them, and
  2372.        this option will force displaying them as well.
  2373. @\item
  2374.   {\bf -e n}: \# Edges to use from each given polygon (default all). Very handy
  2375.        as '-e 1 -4' for freeform data.
  2376. @\item
  2377.   {\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
  2378.        This number is log based 2 of roughly the number of subdivisions of
  2379.        the surface in each axes (see cagd\_lib for more).
  2380. @\item
  2381.   {\bf -4}: Force four polygons per flat bilinear in surface to polygon
  2382.        conversion. Otherwise two polygons only.
  2383. @\item
  2384.   {\bf -z}: Print version number and current defaults.
  2385. @\end{itemize}
  2386.    Some of the options may be turned on in poly3d-h.cfg. They can be then
  2387.  turned off in the command line as -?-.
  2388. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2389. @\subsection{Configuration}
  2390. &Configuration
  2391.    The program can be configured using a configuration file named poly3d-h.cfg.
  2392.    This is a plain ascii file you can edit directly and set the parameters
  2393.  according to the comments there. executing 'poly3d-h -z' will show the
  2394.  current configuration as read from the configuration file.
  2395.    UNIX and MSDOS DJGPP versions only:
  2396.    The configuration file is being searched in the IRIT\_PATH environment
  2397.  variable. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
  2398.    Note IRIT\_PATH must terminate with '/'. If the variables is not set only
  2399.  the current directory is being searched.
  2400.    MSDOS BC++ version only:
  2401.    The configuration file in MSDOS system can be in any directory which is in
  2402.  your path - the same place as the executable is probably a good choice.
  2403.    The program will use 80x87 if it detects one - uses the Turbo C 80x87
  2404.  autodetect, or will run (much!) slower without it...
  2405. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2406. @\subsection{Usage}
  2407. &Usage
  2408.    As this program is not interactive, usage is quite simple, and only
  2409.  control available is using the command lines options.
  2410. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2411. @\section{poly3d-r - A Simple Data Rendering Program}
  2412. !poly3d-r - A Simple Data Rendering Program
  2413. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2414. @\subsection{Introduction}
  2415. &Introduction
  2416.  poly3d-r is a simple rendering program for data files created by the {\em IRIT}
  2417.  solid modeler. poly3d-r generates GIF images with 8 bits per pixel. As a result
  2418.  rendered images are of medium quality. Although reasonably fast, one should
  2419.  use one of several raytracing public domain programs available (such as
  2420.  RAYSHADE which irit2ray can generate data to) for high quality images.
  2421.    poly3d-r uses cosine shading approximation, and flat/Gouraud interpolation.
  2422.  The program performes 4 passes over the input:
  2423.  1. Process the input (parsing.)
  2424.  2. Prepare the polygons by sorting them by their Y after mapping then into
  2425.     screen space.
  2426.  3. Evaluate colors for vertices (using polygon normals if flat shading, or
  2427.     by vertex normals for Gouraud shading).
  2428.  4. Scan the data by scan line basis and dump out image.
  2429.         This programs can handle CONVEX polygons only. From {\em IRIT} one can
  2430.  ensure a model is consisting of convex polygons only by the CONVEX command:
  2431. @\begin{verbatim}
  2432.   CnvxObj = convex( Obj );
  2433. @\end{verbatim}
  2434.  just before saving it into a file. Surfaces are always decomposed into
  2435.  triangles only.
  2436. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2437. @\subsection{Command Line Options}
  2438. &Command line options
  2439. @\begin{verbatim}
  2440.  poly3d-r [-a Ambient] [-c N] [-l X Y Z] [-2] [-m] [-s Xsize Ysize]
  2441.        [-S SubSample] [-g] [-b] [-M Mask] [-f FineNess] [-z] DFiles > Image.gif
  2442. @\end{verbatim}
  2443. @\begin{itemize}
  2444. @\item
  2445.   {\bf -a Ambient}: Sets the ambient intensity (must be in [0.0..1.0] range).
  2446. @\item
  2447.   {\bf -c N}: number of bits per pixel N (must be in [1..8] range).
  2448. @\item
  2449.   {\bf -l X Y Z}: specify the light source normal direction. This vector does not
  2450.      to be unit vector. Only one light source is supported.
  2451. @\item
  2452.   {\bf -2} : Force emulation of 2 light sources at opposite directions as selected
  2453.      via [-l]. This may be useful for models that has no plane specified (i.e.
  2454.      model has no PLANE attribute for its polygons), as the program guess the
  2455.      equation from the points themselves, and which can be to the opposite
  2456.      direction.
  2457. @\item
  2458.   {\bf -m}: More - provide some more information on the data file(s) parsed.
  2459. @\item
  2460.   {\bf -s Xsize Ysize}: specify image dimensions. As the models created by {\em IRIT}
  2461.      are mapped to a unit domain (X in [-1..1], Y in [-1..1]) by the
  2462.      viewing matrix, objects must be scaled up. The scaling up factor is
  2463.      MIN(Xsize, Ysize), which guarantee nothing of the original image will be
  2464.      clipped.
  2465. @\item
  2466.   {\bf -b}: Purge back facing polygons. If the scene contains closed objects (such
  2467.      as the ones usually created by {\em IRIT}), the back facing polygons can be
  2468.      deleted. This would not change the image, but will speed up the process
  2469.      at about %15. Using this option for non complete boundary object and/or
  2470.      objects with polygons with no PLANE specified would almost definitely
  2471.      create wrong image.
  2472. @\item
  2473.   {\bf -g}: Use Gouraud shading interpolation (flat shading is used by default).
  2474.      This is somewhat slower, but gives nicer results.
  2475. @\item
  2476.   {\bf -S SubSample}: sub sample, and uses box filter to low pass filter the
  2477.      image, using SubSample as grid side of SubSample by SubSample.
  2478.      This obviously make things slower, but guess what - it looks much better.
  2479. @\item
  2480.   {\bf -M Mask}: Create a new GIF file named Mask that is a binary image set to 1
  2481.      at any pixel covered by one of the objects or 0 otherwise. As a color of
  2482.      an object can become equal to the background at some point, there is no
  2483.      way to find whether pixel is background or an object in the background
  2484.      color. The Mask can be used instead. This Mask can be used when combining
  2485.      images (such as gifcomp utility in the gif\_lib).
  2486.      This image is a binary alpha channel.
  2487. @\item
  2488.   {\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
  2489.      This number is log based 2 of roughly the number of subdivisions of
  2490.      the surface in each axes (see cagd\_lib for more).
  2491. @\item
  2492.   {\bf -z}: Print version number and current defaults.
  2493. @\end{itemize}
  2494.    The image is dumped to stdout as a GIF image which can be redirected to a
  2495.  file or to be piped to any program that reads GIF images from stdin.
  2496.    Some of the options may be turned on in poly3d-r.cfg. They can be then
  2497.  turned off in the command line as -?-.
  2498. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2499. @\subsection{Configuration}
  2500. &Configuration
  2501.    The program can be configured using a configuration file named poly3d-r.cfg.
  2502.    This is a plain ascii file you can edit directly and set the parameters
  2503.  according to the comments there. executing 'poly3d-r -z' will show the
  2504.  current configuration as read from the configuration file.
  2505.    UNIX and MSDOS DJGPP versions only:
  2506.    The configuration file is being searched in the IRIT\_PATH environment
  2507.  variable. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
  2508.    Note IRIT\_PATH must terminate with '/'. If the variables is not set only
  2509.  the current directory is being searched.
  2510.    MSDOS BC++ version only:
  2511.    The configuration file in MSDOS system can be in any directory which is in
  2512.  your path - the same place as the executable is probably a good choice.
  2513.    The program will use 80x87 if it detects one - uses the Turbo C 80x87
  2514.  autodetect, or will run (much!) slower without it...
  2515. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2516. @\subsection{Usage}
  2517. &Usage
  2518.    As this program is not interactive, usage is quite simple, and only
  2519.  control available is using the command lines options.
  2520.    Some Remarks:
  2521.   1. If the input file is degenerate (2 vertices are identical etc.) they
  2522.      will be ignored is the next passes. Use [-m] if you want to know about
  2523.      them.
  2524.   2. The color of the object can be extract via the COLOR attribute as set
  2525.      via the {\em IRIT} COLOR command. In addition to this fixed set of colors, one
  2526.      can specify the color in RGB space using the ATTRIB command. For example:
  2527. @\begin{verbatim}
  2528.      attrib( Srf17, "rgb", "255,155,55" );
  2529. @\end{verbatim}
  2530.      Each of R G B must be integer is the range [0..255].
  2531. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2532. @\section{Irit2Ray - IRIT To RAYSHADE filter}
  2533. !IRIT2RAY - IRIT To RAYSHADE filter
  2534. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2535. @\subsection{Command Line Options}
  2536. &Command line options
  2537. @\begin{verbatim}
  2538.   irit2ray [-l] [-4] [-G GridSize] [-f FineNess] [-o OutName] [-g] [-z] DFiles
  2539. @\end{verbatim}
  2540. @\begin{itemize}
  2541. @\item
  2542.   {\bf -l}: Linear - forces linear (degree two) surfaces to be approximated
  2543.        as a single polygon along their linear direction.
  2544.          Although most of the time, linear direction can be exactly represented
  2545.        using a single polygon, even a bilinear surface can have a free form
  2546.        shape (saddle like) that is not representable using a single polygon.
  2547.          Not using this option will better emulate the surface shape but
  2548.        will create unnecessary polygons in cases where one is enough.
  2549. @\item
  2550.   {\bf -4}: Four - Generate four polygons per flat patch. Default is 2.
  2551. @\item
  2552.   {\bf -G GridSize}: Usually objects are grouped as {\em lists} of polygons.
  2553.        This flags will coerce the usage of RAYSHADE {\em grid} constructure,
  2554.        with {\em GridSize} being used as the grid size along the object bounding
  2555.        box largest dimension.
  2556. @\item
  2557.   {\bf -f FineNess}: An integer value controling the fineness of surface to
  2558.        polygons process. Roughly speaking it will set to the number of polygons
  2559.        along one Bezier patch direction. A Bezier patch will have order of
  2560.        $FineNess^2$ polygons then. The Order of the surface also affect the
  2561.        amount of polygons; The higher the order is, more polygons are created.
  2562.          A B-spline surface is first converted into piecewise Bezier to make
  2563.        sure C1 discontinuities will show up in the polygonal approximation.
  2564. @\item
  2565.   {\bf -o OutName}: Name of output files. By default the name of the first data
  2566.        file from {\em DFiles} list is used.  See below on the output files.
  2567. @\item
  2568.   {\bf -g}: Generates the geometry file only. See below.
  2569. @\item
  2570.   {\bf -z}: Print version number and current defaults.
  2571. @\end{itemize}
  2572. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2573. @\subsection{Usage}
  2574. &Usage
  2575.     Irit2Ray converts freeform surfaces into polygons in format that can
  2576.  be used by RAYSHADE. Two files are created, one with '.geom' extension and
  2577.  one with '.ray'. Since the number of polygons can be extremely large,
  2578.  the geometry is isolated in the '.geom' and is included (via '\#include') in
  2579.  the main '.ray' file. The later holds the surface properties for all the
  2580.  geometry as well as viewing and RAYSHADE specific commands. This allows
  2581.  changing shading or viewing properties while editing small ('.ray') files.
  2582.     If '-g' is specified, only the '.geom' file is created, preserving the
  2583.  current '.ray' file.
  2584.     In practice it may be useful to create a low resolution approximation
  2585.  of the model, change viewing/shading parameters in the '.ray' file until
  2586.  a good view and/or surface quality is found and then run Irit2Ray once more
  2587.  to create a high resolution approximation of the geometry using '-g'.
  2588.     Here is a simple example:
  2589. @\begin{verbatim}
  2590.  irit2ray -l -f 5 b58.dat
  2591. @\end{verbatim}
  2592.  creates b58.ray and b58.geom with low resolution (FineNess of 5).
  2593.    At such low resolution it can very well may happen that triangles will have
  2594.  normals "over the edge" since a single polygon may approximate a highly
  2595.  curves surface. That will cause rayshade to issue an
  2596.  "Inconsistant triangle normals" warning. This problem will not exist if
  2597.  high fineness is used.
  2598.    One can ray trace this scene using a command similar to:
  2599. @\begin{verbatim}
  2600.  rayshade -p -W 256 256 b58.ray > b58.rle
  2601. @\end{verbatim}
  2602.  Once done with parameter setting for rayshade, a fine approximation of the
  2603.  model can be created with:
  2604. @\begin{verbatim}
  2605.  irit2ray -l -g -f 25 b58.dat
  2606. @\end{verbatim}
  2607.  which will only recreate b58.geom (becuase of the -g option).
  2608.  Each time a data file is saved in {\em IRIT}, it can be saved with the viewing
  2609.  matrix of the last INTERACT by saving the VIEW\_MAT object as well. I.e.:
  2610. @\begin{verbatim}
  2611.  save( "b58", list( view_mat, b58 ) );
  2612. @\end{verbatim}
  2613.  However one can overwrite the viewing matrix by appending a new matrix in the
  2614.  end of the command line, created by poly3d:
  2615. @\begin{verbatim}
  2616.  poly3d b58.dat
  2617.  irit2ray -l -f 5 b58.dat generic0.mat
  2618. @\end{verbatim}
  2619.  where generic0.mat is the viewing matrix created by poly3d.
  2620. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2621. @\subsection{Advanced Usage}
  2622. &Advanced Usage
  2623.    One can specify surface qualities for individual surfaces of a model.
  2624.  Several such attributes are supported by Irit2Ray and can be set within {\em IRIT}.
  2625.  See also the ATTRIB {\em IRIT} command.
  2626.    If a certain surface should be finer than the rest of the scene, one can
  2627.  set a "resolution" attribute which specifies the {\em relative} FineNess resolution
  2628.  of this specific surface. For example:
  2629. @\begin{verbatim}
  2630.  attrib( srf1, "resolution", 2 );
  2631. @\end{verbatim}
  2632.  will force srf1 to have twice the default resolution, as set via the '-f'
  2633.  flag.
  2634.    Almost flat patches are converted to polygons. The rectangle can be
  2635.  converted into two polygons (by subdividing along one of its diagonals) or
  2636.  into four by introducing a new point at the patch center. This behaviour is
  2637.  controlled by the '-4' flag, but can be overwritten for individual surfaces
  2638.  bu setting "twoperflat" or "fourperflat".
  2639.    RAYSHADE specific properties are controlled via the following attributes:
  2640.  "specpow", "reflect", "transp", "body", "index", and "texture". Refer to
  2641.  RAYSHADE manual for their meaning. For example:
  2642. @\begin{verbatim}
  2643.  attrib( srf1, "transp", "0.3" );
  2644.  attrib( srf1, "texture", "wood" );
  2645. @\end{verbatim}
  2646.    Surface color is controlled in two levels. If the object has an RGB
  2647.  attribute it is used. Otherwise a color as set via {\em IRIT} COLOR command
  2648.  is being used if set. The later allowes you to specify only the 3 additive,
  2649.  3 substractive and white and black and so is very limited for rendering
  2650.  purposes. Example:
  2651. @\begin{verbatim}
  2652.  attrib( tankBody, "rgb", "244,164,96" );
  2653. @\end{verbatim}
  2654.    Current implementation allows white spaces in neither the attribute
  2655.  name nor in the attribute value.
  2656. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2657. @\section{Irit2Nff - IRIT To NFF filter}
  2658. !IRIT2NFF - IRIT To NFF filter
  2659. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2660. @\subsection{Command Line Options}
  2661. &Command line options
  2662. @\begin{verbatim}
  2663.   irit2nff [-l] [-4] [-c] [-f FineNess] [-o OutName] [-g] [-z] DFiles
  2664. @\end{verbatim}
  2665. @\begin{itemize}
  2666. @\item
  2667.   {\bf -l}: Linear - forces linear (degree two) surfaces to be approximated
  2668.        as a single polygon along their linear direction.
  2669.          Although most of the time, linear direction can be exactly represented
  2670.        using a single polygon, even a bilinear surface can have a free form
  2671.        shape (saddle like) that is not representable using a single polygon.
  2672.          Not using this option will better emulate the surface shape but
  2673.        will create unnecessary polygons in cases where one is enough.
  2674. @\item
  2675.   {\bf -4}: Four - Generate four polygons per flat patch. Default is 2.
  2676. @\item
  2677.   {\bf -c}: Output files should be filtered by cpp. By doing so, the usually
  2678.        huge geometry file is seperated from the main nff file that contains
  2679.        the surface properties and view parameters. By default all data,
  2680.        including the geometry, is saved into a single file with type extension
  2681.        '.nff'. Use of '-c' will pull out all the geometry into a file with
  2682.        the same name but '.geom' extension and which will be included using
  2683.        '\#include' command. The '.nff' file should, in that case, be
  2684.        preprocessed using cpp before piped into the nff renderer.
  2685. @\item
  2686.   {\bf -f FineNess}: An integer value controling the fineness of surface to
  2687.        polygons process. Roughly speaking it will set to the number of polygons
  2688.        along one Bezier patch direction. A Bezier patch will have order of
  2689.        $FineNess^2$ polygons then. The Order of the surface also affect the
  2690.        amount of polygons; The higher the order is, more polygons are created.
  2691.          A B-spline surface is first converted into piecewise Bezier to make
  2692.        sure C1 discontinuities will show up in the polygonal approximation.
  2693. @\item
  2694.   {\bf -o OutName}: Name of output files. By default the name of the first data
  2695.        file from {\em DFiles} list is used.  See below on the output files.
  2696. @\item
  2697.   {\bf -g}: Generates the geometry file only. See below.
  2698. @\item
  2699.   {\bf -z}: Print version number and current defaults.
  2700. @\end{itemize}
  2701. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2702. @\subsection{Usage}
  2703. &Usage
  2704.     Irit2Nff converts freeform surfaces into polygons in format that can
  2705.  be used by NFF renderer. Usually one file is created with '.nff' type
  2706.  extension. Since the number of polygons can be extremely large, a '-c'
  2707.  option is provided and which separate the geometry from the surface
  2708.  properties and view specification but requires preprocessing by cpp.
  2709.  The geometry is isolated in a file with extension '.geom' and included
  2710.  (via '\#include') in the main '.nff' file. The later holds the surface
  2711.  properties for all the geometry as well as the viewing specification.
  2712.  This allows changing shading or viewing properties while editing small
  2713.  ('.nff') files.
  2714.     If '-g' is specified, only the '.geom' file is created, preserving the
  2715.  current '.nff' file. The '-g' flag can be specified only with '-c'.
  2716.     In practice it may be useful to create a low resolution approximation
  2717.  of the model, change viewing/shading parameters in the '.nff' file until
  2718.  a good view and/or surface quality is found and then run Irit2Nff once more
  2719.  to create a high resolution approximation of the geometry using '-g'.
  2720.     Here is a simple example:
  2721. @\begin{verbatim}
  2722.  irit2nff -c -l -f 5 b58.dat
  2723. @\end{verbatim}
  2724.  creates b58.nff and b58.geom with low resolution (FineNess of 5).
  2725.  Once done with parameter setting, a fine approximation of the model can
  2726.  be created with:
  2727. @\begin{verbatim}
  2728.  irit2nff -c -l -g -f 25 b58.dat
  2729. @\end{verbatim}
  2730.  which will only recreate b58.geom (becuase of the -g option).
  2731.  Each time a data file is saved in {\em IRIT}, it can be saved with the viewing
  2732.  matrix of the last INTERACT by saving the VIEW\_MAT object as well. I.e.:
  2733. @\begin{verbatim}
  2734.  save( "b58", list( view_mat, b58 ) );
  2735. @\end{verbatim}
  2736.  However one can overwrite the viewing matrix by appending a new matrix in the
  2737.  end of the command line, created by poly3d:
  2738. @\begin{verbatim}
  2739.  poly3d b58.dat
  2740.  irit2nff -l -f 5 b58.dat generic0.mat
  2741. @\end{verbatim}
  2742.  where generic0.mat is the viewing matrix created by poly3d.
  2743. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2744. @\subsection{Advanced Usage}
  2745. &Advanced Usage
  2746.    One can specify surface qualities for individual surfaces of a model.
  2747.  Several such attributes are supported by Irit2Nff and can be set within {\em IRIT}.
  2748.  See also the ATTRIB {\em IRIT} command.
  2749.    If a certain surface should be finer than the rest of the scene, one can
  2750.  set a "resolution" attribute which specifies the {\em relative} FineNess resolution
  2751.  of this specific surface. For example:
  2752. @\begin{verbatim}
  2753.  attrib( srf1, "resolution", 2 );
  2754. @\end{verbatim}
  2755.  will force srf1 to have twice the default resolution, as set via the '-f'
  2756.  flag.
  2757.    Almost flat patches are converted to polygons. The rectangle can be
  2758.  converted into two polygons (by subdividing along one of its diagonals) or
  2759.  into four by introducing a new point at the patch center. This behaviour is
  2760.  controlled by the '-4' flag, but can be overwritten for individual surfaces
  2761.  bu setting "twoperflat" or "fourperflat".
  2762.    NFF specific properties are controlled via the following attributes:
  2763.  "kd", "ks", "shine", "trans", "index". Refer to NFF manual for detail.
  2764.  For example:
  2765. @\begin{verbatim}
  2766.  attrib( srf1, "kd", "0.3" );
  2767.  attrib( srf1, "shine", "30" );
  2768. @\end{verbatim}
  2769.    Surface color is controlled in two levels. If the object has an RGB
  2770.  attribute it is used. Otherwise a color as set via {\em IRIT} COLOR
  2771.  command is being used if set. The later allowes you to specify only the
  2772.  3 additive, 3 substractive and white and black and so is very limited for
  2773.  rendering purposes. Example:
  2774. @\begin{verbatim}
  2775.  attrib( tankBody, "rgb", "244,164,96" );
  2776. @\end{verbatim}
  2777.    Current implementation allows white spaces in neither the attribute
  2778.  name nor in the attribute value.
  2779. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2780. @\section{Dat2Irit - Data To IRIT file filter}
  2781. !DAT2IRIT - Data To IRIT file filter
  2782. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2783. @\subsection{Command Line Options}
  2784. &Command line options
  2785. @\begin{verbatim}
  2786.    dat2irit [-z] DFiles
  2787. @\end{verbatim}
  2788. @\begin{itemize}
  2789. @\item
  2790.   {\bf -z}: Print version number and current defaults.
  2791. @\end{itemize}
  2792. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2793. @\subsection{Usage}
  2794. &Usage
  2795.     It may be sometimes desired to convert .dat data files into a form that
  2796.  can be fed in back to {\em IRIT} - a '.irt' file. This filter will do exactly that.
  2797.  Example:
  2798. @\begin{verbatim}
  2799.    dat2irit b58.dat > b58-new.irt
  2800. @\end{verbatim}
  2801. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
  2802. @\section{Data File Format}
  2803. !DATAFILE Format
  2804.    This section describes the data file format used to exchange data between
  2805.  {\em IRIT} and its accompanied tools.
  2806. @\begin{verbatim}
  2807.  [OBJECT {ATTRS} OBJNAME
  2808.      [NUMBER n]
  2809.    | [VECTOR x y z]
  2810.    | [CTLPT POINT_TYPE {w} x y {z}]
  2811.    | [STRING "a string"]
  2812.    | [MATRIX m00 ... m03
  2813.              m10 ... m13
  2814.              m20 ... m23
  2815.              m30 ... m33]
  2816.      ;A polyline should be drawn from first point to last. Nothing is drawn
  2817.      ;from last to first (in close polyline last pt is equal to first).
  2818.    | [POLYLINE {ATTRS} #PTS                   ;#PTS = number of points.
  2819.          [{ATTRS} x y z]
  2820.          [{ATTRS} x y z]
  2821.             .
  2822.             .
  2823.             .
  2824.          [{ATTRS} x y z]
  2825.      ]
  2826.      ;Defines a closed region boundary. Last point is NOT equal to first
  2827.      ;and a line from last point to first should be drawn when the polygon
  2828.      ;boundary is drawn.
  2829.    | [POLYGON {ATTRS} #PTS
  2830.          [{ATTRS} x y z]
  2831.          [{ATTRS} x y z]
  2832.             .
  2833.             .
  2834.             .
  2835.          [{ATTRS} x y z]
  2836.      ]
  2837.      ;Defines a cloud of points. This entry is not supported by IRIT.
  2838.    | [POINTLIST {ATTRS} #PTS
  2839.          [{ATTRS} x y z]
  2840.          [{ATTRS} x y z]
  2841.             .
  2842.             .
  2843.             .
  2844.          [{ATTRS} x y z]
  2845.      ]
  2846.      ;Defines a bezier curve with #PTS control points. If the curve is
  2847.      ;rational, the rational component is introduced first.
  2848.    | [CURVE BEZIER {ATTRS} #PTS POINT_TYPE
  2849.          [{ATTRS} {w} x y z ...]
  2850.          [{ATTRS} {w} x y z ...]
  2851.             .
  2852.             .
  2853.             .
  2854.          [{ATTRS} {w} x y z ...]
  2855.      ]
  2856.      ;Defines a bezier surface with #UPTS * #VPTS control points. If the
  2857.      ;surface is rational, the rational component is introduced first.
  2858.      ;Points are printed raw after raw (#UPTS per raw), #VPTS raws.
  2859.    | [SURFACE BEZIER {ATTRS} #UPTS #VPTS POINT_TYPE
  2860.          [{ATTRS} {w} x y z ...]
  2861.          [{ATTRS} {w} x y z ...]
  2862.             .
  2863.             .
  2864.             .
  2865.          [{ATTRS} {w} x y z ...]
  2866.      ]
  2867.      ;Defines a BSPLINE curve of order ORDER with #PTS control points. If the
  2868.      ;curve is rational, the rational component is introduced first.
  2869.      ;Note length of knot vector is equal to #PTS + ORDER.
  2870.    | [CURVE BSPLINE {ATTRS} #PTS ORDER POINT_TYPE
  2871.          [KV {ATTRS} kv0 kv1 kv2 ...]                    ;Knot vector
  2872.          [{ATTRS} {w} x y z ...]
  2873.          [{ATTRS} {w} x y z ...]
  2874.             .
  2875.             .
  2876.             .
  2877.          [{ATTRS} {w} x y z ...]
  2878.      ]
  2879.      ;Defines a BSPLINE surface with #UPTS * #VPTS control points, of order
  2880.      ;UORDER by VORDER. If the surface is rational, the rational component
  2881.      ;is introduced first.
  2882.      ;Points are printed raw after raw (#UPTS per raw), #VPTS raws.
  2883.    | [SURFACE BSPLINE {ATTRS} #UPTS #VPTS UORDER VORDER POINT_TYPE
  2884.          [KV {ATTRS} kv0 kv1 kv2 ...]                ;U Knot vector
  2885.          [KV {ATTRS} kv0 kv1 kv2 ...]                ;V Knot vector
  2886.          [{ATTRS} {w} x y z ...]
  2887.          [{ATTRS} {w} x y z ...]
  2888.             .
  2889.             .
  2890.             .
  2891.          [{ATTRS} {w} x y z ...]
  2892.      ]
  2893.  POINT_TYPE -> E2 | E3 | P2 | P3
  2894.  ATTRS -> [ATTRNAME ATTRVALUE]
  2895.           | [ATTRNAME ATTRVALUE] ATTRS
  2896. @\end{verbatim}
  2897.  Some notes:
  2898.  1. This new definition for the text file is design to minimize the
  2899.     reading time and space. All information can be read without backward
  2900.     or forward referencing (as used to be in the old format).
  2901.  2. An OBJECT can hold any number of geometry entities such as POLYGONs or
  2902.     CURVEs. It is not recommended at this time to have more than one curve
  2903.     or one surface in an object since this feature is not fully implemented
  2904.     for free form objects.
  2905.  3. An OBJECT must not hold different geometry or other entities.
  2906.     I.e. CURVEs, SURFACEs, and POLYGONs must all be in different OBJECTs.
  2907.  4. Attributes should be ignored if not needed. The attribute list may have
  2908.     any length and is always terminated by a token that is NOT '\verb+[+'. This
  2909.     simplified and disambiguous the parsing.
  2910.  5. Comments may appear between '\verb+[+OBJECT ...\verb+]+' blocks, or immediatelly after
  2911.     OBJECT OBJNAME, and only there.
  2912.     A comment body can be anything not containing the '\verb+[+' or the '\verb+]+' tokens
  2913.     (signals start/end of block). Some of the comments in the above definition
  2914.     are {\em illegal} and appear there only of the sake of clarity.
  2915.  6. It is prefered that geometric attributes such as NORNALs will be saved in
  2916.     the geometry strurcture level (POLYGON, CURVE or vertices) while graphical
  2917.     and others such as COLORs will be saved in the OBJECT level.
  2918.  7. Objects may be contained in other objects to any level.
  2919.  Here is an example that exercises most of the data format:
  2920. @\begin{verbatim}
  2921.  This is a legal comment in a data file.
  2922.  [OBJECT DEMO
  2923.      [OBJECT REAL_NUM
  2924.          And this is also a legal comment.     
  2925.          [NUMBER 4]
  2926.      ]
  2927.      [OBJECT A_VECTOR
  2928.          [VECTOR 1 2 3]
  2929.      ]
  2930.      [OBJECT CTL_POINT
  2931.          [CTLPT E3 1 2 3]
  2932.      ]
  2933.      [OBJECT STR_OBJ
  2934.          [STRING "string"]
  2935.      ]
  2936.      [OBJECT UNIT_MAT
  2937.          [MATRIX
  2938.             1 0 0 0
  2939.             0 1 0 0
  2940.             0 0 1 0
  2941.             0 0 0 1
  2942.          ]
  2943.      ]
  2944.      [OBJECT [COLOR 4] POLY1OBJ
  2945.          [POLYGON [PLANE 1 0 0 0.5] 4
  2946.              [-0.5 0.5 0.5]
  2947.              [-0.5 -0.5 0.5]
  2948.              [-0.5 -0.5 -0.5]
  2949.              [-0.5 0.5 -0.5]
  2950.          ]
  2951.          [POLYGON [PLANE 0 -1 0 0.5] 4
  2952.              [0.5 0.5 0.5]
  2953.              [-0.5 0.5 0.5]
  2954.              [-0.5 0.5 -0.5]
  2955.              [0.5 0.5 -0.5]
  2956.          ]
  2957.      ]
  2958.      [OBJECT [COLOR 63] ACURVE
  2959.          [CURVE BSPLINE 16 4 E2
  2960.              [KV 0 0 0 0 1 1 1 2 3 4 5 6 7 8 9 10 11 11 11 11]
  2961.              [0.874 0]
  2962.              [0.899333 0.0253333]
  2963.              [0.924667 0.0506667]
  2964.              [0.95 0.076]
  2965.              [0.95 0.76]
  2966.              [0.304 1.52]
  2967.              [0.304 1.9]
  2968.              [0.494 2.09]
  2969.              [0.722 2.242]
  2970.              [0.722 2.318]
  2971.              [0.38 2.508]
  2972.              [0.418 2.698]
  2973.              [0.57 2.812]
  2974.              [0.57 3.42]
  2975.              [0.19 3.572]
  2976.              [0 3.572]
  2977.          ]
  2978.      ]
  2979.      [OBJECT [COLOR 2] SOMESRF
  2980.          [SURFACE BEZIER 3 3 E3
  2981.              [0 0 0]
  2982.              [0.05 0.2 0.1]
  2983.              [0.1 0.05 0.2]
  2984.              [0.1 -0.2 0]
  2985.              [0.15 0.05 0.1]
  2986.              [0.2 -0.1 0.2]
  2987.              [0.2 0 0]
  2988.              [0.25 0.2 0.1]
  2989.              [0.3 0.05 0.2]
  2990.          ]
  2991.      ]
  2992. @\end{verbatim}
  2993. @\section{Bugs and Limitations}
  2994. !BUGS and LIMITATIONS
  2995.    Like any program of more than one line it is far from been perfect.
  2996.  Some limitations as well as simplifications are layed out below.
  2997.  1. No intersection of co-planar polygons is allowed. Such case results are
  2998.     undefined. Most of the time, one can move one of the operands
  2999.     in the Boolean operation by an EPSILON. Such EPSILON should be in the
  3000.     order of 10-3 if the system uses float and and 10-6 if doubles are used.
  3001.     (the UNIX and MSDOS DJGPP version uses doubles, MSDOS BC++ uses floats).
  3002.  2. If the intersection curve of two objects falls exactly on polygon
  3003.     boundaries, for all polygons, the system will scream that the two object
  3004.     do not intersect at all. Again, try to move one by EPSILON into the other.
  3005.     I probably should fix this one - that suppose to be relatively easy.
  3006.  3. Avoid degeneracies - intersection that results with a point or a line will
  3007.     probably cause wrong propagation of the inner and outer part of one object
  3008.     relative to the other. Always extend your object beyond the other object.
  3009.  4. If two objects have no intersection in their boundary, {\em IRIT} assumes they
  3010.     are disjoint: a union simply combines them, and the other Boolean
  3011.     operators return NULL object. One should find FAST way (3D Jordan
  3012.     theorem) to find the relation between the two (A in B, B in A, A
  3013.     disjoint B) and according to that make a decision.
  3014.  5. Sweep of a circular curve along circular curve does {\em not} create an
  3015.     exact piece of a torus. This is probably due to the fact that both curves
  3016.     are rationals.
  3017.  6. No degree raising for Bspline surfaces of order larger than two.
  3018. @\end{document}
  3019.